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This topic provides a guided tour of the Windows Presentation Foundation (WPF) class hierarchy. It covers most of 
the major subsystems of WPF, and describes how they interact. It also details some of the choices made by the 
architects of WPF. 

System. Object 

The primary WPF programming model is exposed through managed code. Early in the design phase of WPF there 
were a number of debates about where the line should be drawn between the managed components of the 
system and the unmanaged ones. The CLR provides a number of features that make development more 
productive and robust (including memory management, error handling, common type system, etc.) but they come 
at a cost. 

The major components of WPF are illustrated in the figure below. The red sections of the diagram 
(PresentationFramework, PresentationCore, and milcore) are the major code portions of WPF. Of these, only one 
is an unmanaged component - milcore. Milcore is written in unmanaged code in order to enable tight integration 
with DirectX. All display in WPF is done through the DirectX engine, allowing for efficient hardware and software 
rendering. WPF also required fine control over memory and execution. The composition engine in milcore is 
extremely performance sensitive, and required giving up many advantages of the CLR to gain performance. 
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Communication between the managed and unmanaged portions of WPF is discussed later in this topic. The 
remainder of the managed programming model is described below. 

System.Threading.DispatcherObJect 

Most objects in WPF derive from DispatcherObject, which provides the basic constructs for dealing with 
concurrency and threading. WPF is based on a messaging system implemented by the dispatcher. This works 
much like the familiar Win32 message pump; in fact, the WPF dispatcher uses User32 messages for performing 













cross thread calls. 


There are really two core concepts to understand when discussing concurrency in WPF - the dispatcher and 
thread affinity. 

During the design phase of WPF, the goal was to move to a single thread of execution, but a non-thread 
"affinitized" model. Thread affinity happens when a component uses the identity of the executing thread to store 
some type of state. The most common form of this is to use the thread local store (TLS) to store state. Thread 
affinity requires that each logical thread of execution be owned by only one physical thread in the operating 
system, which can become memory intensive. In the end, WPF's threading model was kept in sync with the 
existing User32 threading model of single threaded execution with thread affinity. The primary reason for this was 
interoperability - systems like OLE 2.0, the clipboard, and Internet Explorer all require single thread affinity (STA) 
execution. 

Given that you have objects with STA threading, you need a way to communicate between threads, and validate 
that you are on the correct thread. Herein lies the role of the dispatcher. The dispatcher is a basic message 
dispatching system, with multiple prioritized queues. Examples of messages include raw input notifications 
(mouse moved), framework functions (layout), or user commands (execute this method). By deriving from 
DispatcherObject, you create a CLR object that has STA behavior, and will be given a pointer to a dispatcher at 
creation time. 

System.Windows.DependencyObject 

One of the primary architectural philosophies used in building WPF was a preference for properties over methods 
or events. Properties are declarative and allow you to more easily specify intent instead of action. This also 
supported a model driven, or data driven, system for displaying user interface content. This philosophy had the 
intended effect of creating more properties that you could bind to, in order to better control the behavior of an 
application. 

In order to have more of the system driven by properties, a richer property system than what the CLR provides 
was needed. A simple example of this richness is change notifications. In order to enable two way binding, you 
need both sides of the bind to support change notification. In order to have behavior tied to property values, you 
need to be notified when the property value changes. The Microsoft .NET Framework has an interface, 
INotifyPropertyChange, which allows an object to publish change notifications, however it is optional. 

WPF provides a richer property system, derived from the DependencyObject type. The property system is truly a 
"dependency" property system in that it tracks dependencies between property expressions and automatically 
revalidates property values when dependencies change. For example, if you have a property that inherits (like 
FontSize), the system is automatically updated if the property changes on a parent of an element that inherits the 
value. 

The foundation of the WPF property system is the concept of a property expression. In this first release of WPF, 
the property expression system is closed, and the expressions are all provided as part of the framework. 
Expressions are why the property system doesn't have data binding, styling, or inheritance hard coded, but rather 
provided by later layers within the framework. 

The property system also provides for sparse storage of property values. Because objects can have dozens (if not 
hundreds) of properties, and most of the values are in their default state (inherited, set by styles, etc.), not every 
instance of an object needs to have the full weight of every property defined on it. 

The final new feature of the property system is the notion of attached properties. WPF elements are built on the 
principle of composition and component reuse. It is often the case that some containing element (like a Grid 
layout element) needs additional data on child elements to control its behavior (like the Row/Column 
information). Instead of associating all of these properties with every element, any object is allowed to provide 
property definitions for any other object. This is similar to the "expando" features of JavaScript. 


System.Windows.Media.Visual 

With a system defined, the next step is getting pixels drawn to the screen. The Visual class provides for building a 
tree of visual objects, each optionally containing drawing instructions and metadata about how to render those 
instructions (clipping, transformation, etc.). Visual is designed to be extremely lightweight and flexible, so most of 
the features have no public API exposure and rely heavily on protected callback functions. 

Visual is really the entry point to the WPF composition system. Visual is the point of connection between these 
two subsystems, the managed API and the unmanaged milcore. 

WPF displays data by traversing the unmanaged data structures managed by the milcore. These structures, called 
composition nodes, represent a hierarchical display tree with rendering instructions at each node. This tree, 
illustrated on the right hand side of the figure below, is only accessible through a messaging protocol. 

When programming WPF, you create Visual elements, and derived types, which internally communicate to the 
composition tree through this messaging protocol. Each Visual in WPF may create one, none, or several 
composition nodes. 



There is a very important architectural detail to notice here - the entire tree of visuals and drawing instructions is 
cached. In graphics terms, WPF uses a retained rendering system. This enables the system to repaint at high 
refresh rates without the composition system blocking on callbacks to user code. This helps prevent the 
appearance of an unresponsive application. 

Another important detail that isn't really noticeable in the diagram is how the system actually performs 
composition. 

In User32 and GDI, the system works on an immediate mode clipping system. When a component needs to be 
rendered, the system establishes a clipping bounds outside of which the component isn't allowed to touch the 
pixels, and then the component is asked to paint pixels in that box. This system works very well in memory 
constrained systems because when something changes you only have to touch the affected component - no two 
components ever contribute to the color of a single pixel. 

WPF uses a "painter's algorithm" painting model. This means that instead of clipping each component, each 
component is asked to render from the back to the front of the display. This allows each component to paint over 
the previous component's display. The advantage of this model is that you can have complex, partially transparent 
shapes. With today's modern graphics hardware, this model is relatively fast (which wasn't the case when User32/ 
GDI were created). 

As mentioned previously, a core philosophy of WPF is to move to a more declarative, "property centric" model of 
programming. In the visual system, this shows up in a couple of interesting places. 

First, if you think about the retained mode graphic system, this is really moving away from an imperative 
DrawLine/DrawLine type model, to a data oriented model - new Line()/new Line(). This move to data driven 





rendering allows complex operations on the drawing instructions to be expressed using properties. The types 
deriving from Drawing are effectively the object model for rendering. 

Second, if you evaluate the animation system, you'll see that it is almost completely declarative. Instead of 
requiring a developer to compute the next location, or next color, you can express animations as a set of 
properties on an animation object. These animations can then express the intent of the developer or designer 
(move this button from here to there in 5 seconds), and the system can determine the most efficient way to 
accomplish that. 

System.Windows.U I Element 

UlElement defines core subsystems including Layout, Input, and Events. 

Layout is a core concept in WPF. In many systems there is either a fixed set of layout models (HTML supports three 
models for layout; flow, absolute, and tables) or no model for layout (Llser32 really only supports absolute 
positioning). WPF started with the assumption that developers and designers wanted a flexible, extensible layout 
model, which could be driven by property values rather than imperative logic. At the UlElement level, the basic 
contract for layout is introduced - a two phase model with Measure and Arrange passes. 

Measure allows a component to determine how much size it would like to take. This is a separate phase from 
Arrange because there are many situations where a parent element will ask a child to measure several times to 
determine its optimal position and size. The fact that parent elements ask child elements to measure demonstrates 
another key philosophy of WPF - size to content. All controls in WPF support the ability to size to the natural size 
of their content. This makes localization much easier, and allows for dynamic layout of elements as things resize. 
The Arrange phase allows a parent to position and determine the final size of each child. 

A lot of time is often spent talking about the output side of WPF - Visual and related objects. However there is a 
tremendous amount of innovation on the input side as well. Probably the most fundamental change in the input 
model for WPF is the consistent model by which input events are routed through the system. 

Input originates as a signal on a kernel mode device driver and gets routed to the correct process and thread 
through an intricate process involving the Windows kernel and User32. Once the User32 message corresponding 
to the input is routed to WPF, it is converted into a WPF raw input message and sent to the dispatcher. WPF allows 
for raw input events to be converted to multiple actual events, enabling features like "MouseEnter" to be 
implemented at a low level of the system with guaranteed delivery. 

Each input event is converted to at least two events - a "preview" event and the actual event. All events in WPF 
have a notion of routing through the element tree. Events are said to "bubble" if they traverse from a target up the 
tree to the root, and are said to "tunnel" if they start at the root and traverse down to a target. Input preview 
events tunnel, enabling any element in the tree an opportunity to filter or take action on the event. The regular 
(non-preview) events then bubble from the target up to the root. 

This split between the tunnel and bubble phase makes implementation of features like keyboard accelerators 
work in a consistent fashion in a composite world. In User32 you would implement keyboard accelerators by 
having a single global table containing all the accelerators you wanted to support (Ctrl + N mapping to "New"). In 
the dispatcher for your application you would call TranslateAccelerator which would sniff the input messages in 
User32 and determine if any matched a registered accelerator. In WPF this wouldn't work because the system is 
fully "composable" - any element can handle and use any keyboard accelerator. Having this two phase model for 
input allows components to implement their own "TranslateAccelerator". 

To take this one step further, UlElement also introduces the notion of CommandBindings. The WPF command 
system allows developers to define functionality in terms of a command end point - something that implements 
ICommand. Command bindings enable an element to define a mapping between an input gesture (Ctrl + N) and a 
command (New). Both the input gestures and command definitions are extensible, and can be wired together at 
usage time. This makes it trivial, for example, to allow an end user to customize the key bindings that they want to 
use within an application. 


To this point in the topic, "core" features of WPF - features implemented in the PresentationCore assembly, have 
been the focus. When building WPF, a clean separation between foundational pieces (like the contract for layout 
with Measure and Arrange) and framework pieces (like the implementation of a specific layout like Grid) was 
the desired outcome. The goal was to provide an extensibility point low in the stack that would allow external 
developers to create their own frameworks if needed. 

System.Windows.FrameworkElement 

FrameworkElement can be looked at in two different ways. It introduces a set of policies and customizations on 
the subsystems introduced in lower layers of WPF. It also introduces a set of new subsystems. 

The primary policy introduced by FrameworkElement is around application layout. FrameworkElement builds on 
the basic layout contract introduced by UlElement and adds the notion of a layout "slot" that makes it easier for 
layout authors to have a consistent set of property driven layout semantics. Properties like HorizontalAlignment, 
VerticalAlignment, MinWidth, and Margin (to name a few) give all components derived from FrameworkElement 
consistent behavior inside of layout containers. 

FrameworkElement also provides easier API exposure to many features found in the core layers of WPF. For 
example, FrameworkElement provides direct access to animation through the BeginStoryboard method. A 
Storyboard provides a way to script multiple animations against a set of properties. 

The two most critical things that FrameworkElement introduces are data binding and styles. 

The data binding subsystem in WPF should be relatively familiar to anyone that has used Windows Forms or 
ASP.NET for creating an application user interface (Ul). In each of these systems, there is a simple way to express 
that you want one or more properties from a given element to be bound to a piece of data. WPF has full support 
for property binding, transformation, and list binding. 

One of the most interesting features of data binding in WPF is the introduction of data templates. Data templates 
allow you to declaratively specify how a piece of data should be visualized. Instead of creating a custom user 
interface that can be bound to data, you can instead turn the problem around and let the data determine the 
display that will be created. 

Styling is really a lightweight form of data binding. Using styling you can bind a set of properties from a shared 
definition to one or more instances of an element. Styles get applied to an element either by explicit reference (by 
setting the Style property) or implicitly by associating a style with the CLR type of the element. 

System.Windows.Controls.Control 

Control's most significant feature is templating. If you think about WPF's composition system as a retained mode 
rendering system, templating allows a control to describe its rendering in a parameterized, declarative manner. A 
ControlTemplate is really nothing more than a script to create a set of child elements, with bindings to properties 
offered by the control. 

Control provides a set of stock properties, Foreground, Background, Padding, to name a few, which template 
authors can then use to customize the display of a control. The implementation of a control provides a data model 
and interaction model. The interaction model defines a set of commands (like Close for a window) and bindings to 
input gestures (like clicking the red X in the upper corner of the window). The data model provides a set of 
properties to either customize the interaction model or customize the display (determined by the template). 

This split between the data model (properties), interaction model (commands and events), and display model 
(templates) enables complete customization of a control's look and behavior. 

A common aspect of the data model of controls is the content model. If you look at a control like Button, you will 
see that it has a property named "Content" of type Object. In Windows Forms and ASP.NET, this property would 
typically be a string - however that limits the type of content you can put in a button. Content for a button can 


either be a simple string, a complex data object, or an entire element tree. In the case of a data object, the data 
template is used to construct a display. 

Summary 

WPF is designed to allow you to create dynamic, data driven presentation systems. Every part of the system is 
designed to create objects through property sets that drive behavior. Data binding is a fundamental part of the 
system, and is integrated at every layer. 

Traditional applications create a display and then bind to some data. In WPF, everything about the control, every 
aspect of the display, is generated by some type of data binding. The text found inside a button is displayed by 
creating a composed control inside of the button and binding its display to the button's content property. 

When you begin developing WPF based applications, it should feel very familiar. You can set properties, use 
objects, and data bind in much the same way that you can using Windows Forms or ASP.NET. With a deeper 
investigation into the architecture of WPF, you'll find that the possibility exists for creating much richer 
applications that fundamentally treat data as the core driver of the application. 
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Extensible Application Markup Language (XAML) is a markup language for declarative application programming. 
Windows Presentation Foundation (WPF) implements a XAML processor implementation and provides XAML 
language support. The WPF types are implemented such that they can provide the required type backing for a 
XAML representation. In general, you can create the majority of your WPF application Ul in XAML markup. 
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This article describes the features of the XAML language and demonstrates how you can use XAML to write 
Windows Presentation Foundation (WPF) apps. This article specifically describes XAML as implemented by 
WPF. XAML itself is a larger language concept than WPF. 


IMPORTANT 

The Desktop Guide documentation is under construction. 


What is XAML 


XAML is a declarative markup language. As applied to the .NET Core programming model, XAML simplifies 
creating a Ul for a .NET Core app. You can create visible Ul elements in the declarative XAML markup, and then 
separate the Ul definition from the run-time logic by using code-behind files that are joined to the markup 
through partial class definitions. XAML directly represents the instantiation of objects in a specific set of 
backing types defined in assemblies. This is unlike most other markup languages, which are typically an 
interpreted language without such a direct tie to a backing type system. XAML enables a workflow where 
separate parties can work on the Ul and the logic of an app, using potentially different tools. 

When represented as text, XAML files are XML files that generally have the .xami extension. The files can be 
encoded by any XML encoding, but encoding as UTF-8 is typical. 

The following example shows how you might create a button as part of a UL This example is intended to give 
you a flavor of how XAML represents common Ul programming metaphors (it is not a complete sample). 

<StackPanel> 

<Button Content="Cllck Me"/> 

</StackPanel> 


XAML syntax in brief 

The following sections explain the basic forms of XAML syntax, and give a short markup example. These 
sections are not intended to provide complete information about each syntax form, such as how these are 
represented in the backing type system. For more information about the specifics of XAML syntax, see XAML 
Syntax In Detail. 

Much of the material in the next few sections will be elementary to you if you have previous familiarity with 
the XML language. This is a consequence of one of the basic design principles of XAML. The XAML language 
defines concepts of its own, but these concepts work within the XML language and markup form. 

XAML object elements 

An object element typically declares an instance of a type. That type is defined in the assemblies referenced by 
the technology that uses XAML as a language. 

Object element syntax always starts with an opening angle bracket ( < ). This is followed by the name of the 
type where you want to create an instance. (The name can include a prefix, a concept that will be explained 
later.) After this, you can optionally declare attributes on the object element. To complete the object element 
tag, end with a closing angle bracket ( > ). You can instead use a self-closing form that does not have any 








content, by completing the tag with a forward slash and closing angle bracket in succession ( /> ). For example, 
look at the previously shown markup snippet again. 



name of a class that is defined by WPF and is part of the WPF assemblies. When you specify an object element 
tag, you create an instruction for XAML processing to create a new instance of the underlying type. Each 
instance is created by calling the parameterless constructor of the underlying type when parsing and loading 
the XAML. 

Attribute syntax (properties) 

Properties of an object can often be expressed as attributes of the object element. The attribute syntax names 
the object property that is being set, followed by the assignment operator (=). The value of an attribute is 
always specified as a string that is contained within quotation marks. 

Attribute syntax is the most streamlined property setting syntax and is the most intuitive syntax to use for 
developers who have used markup languages in the past. For example, the following markup creates a button 
that has red text and a blue background in addition to display text specified as content . 

<Button Background="Blue" Foregnound="Red" Content="This is a button"/> 


Property element syntax 

For some properties of an object element, attribute syntax is not possible, because the object or information 
necessary to provide the property value cannot be adequately expressed within the quotation mark and string 
restrictions of attribute syntax. For these cases, a different syntax known as property element syntax can be 
used. 

The syntax for the property element start tag is <TypeName.PropertyName> . Generally, the content of that tag is 
an object element of the type that the property takes as its value. After specifying the content, you must close 
the property element with an end tag. The syntax for the end tag is </TypeName.PropertyName> . 

If an attribute syntax is possible, using the attribute syntax is typically more convenient and enables a more 
compact markup, but that is often just a matter of style, not a technical limitation. The following example 
shows the same properties being set as in the previous attribute syntax example, but this time by using 
property element syntax for all properties of the Button . 

<Button> 

<Button.Background> 

<SolidColorBrush Color="Blue"/> 

</Button.Backgrounds 
<Button.Foregrounds 

<SolidColorBrush Color="Red"/s 
</Button.Foregrounds 
<Button.Contents 
This is a button 
</Button.Contents 
</Buttons 


Collection syntax 

The XAML language includes some optimizations that produce more human-readable markup. One such 












optimization is that if a particular property takes a collection type, then items that you declare in markup as 
child elements within that property's value become part of the collection. In this case a collection of child 
object elements is the value being set to the collection property. 

The following example shows collection syntax for setting values of the GradientStops property. 

<LinearGradientBrush> 

<LinearGradientBrush.GradientStops> 

<!-- no explicit new GradientStopCollection, parser knows how to find or create --> 

<GradientStop Offset="0.0" Color="Red" /> 

<GradientStop Offset="1.0" Color="Blue" /> 

</LinearGradientBrush.GradientStops> 

</LinearGradientBrush> 


XAML content properties 

XAML specifies a language feature whereby a class can designate exactly one of its properties to be the XAML 
corrterrf property. Child elements of that object element are used to set the value of that content property. In 
other words, for the content property uniquely, you can omit a property element when setting that property in 
XAML markup and produce a more visible parent/child metaphor in the markup. 

For example, Border specifies a co/rferrf property of Child. The following two Border elements are treated 



As a rule of the XAML language, the value of a XAML content property must be given either entirely before or 
entirely after any other property elements on that object element. For instance, the following markup does not 
compile. 

<Button>I am a 

<Button.BackgnoundxBluec/Button.Background> 
blue button</Button> 


For more information about the specifics of XAML syntax, see XAML Syntax In Detail. 

Text content 

A small number of XAML elements can directly process text as their content. To enable this, one of the 
following cases must be true: 

• The class must declare a content property, and that content property must be of a type assignable to a 
string (the type could be Object). For instance, any ContentControl uses Content as its content property 
and it is type Object, and this supports the following usage on a ContentControl such as a Button: 
<Button>Hello</Button> . 


• The type must declare a type converter, in which case the text content is used as initialization text for 
that type converter. For example, <Br'ush>Biue</Brush> converts the content value of Blue into a brush. 
This case is less common in practice. 









• The type must be a known XAML language primitive. 


Content properties and collection syntax combined 

Consider this example. 

<StackPanel> 

<Button>First Button</Button> 

<Button>Second Button</Button> 

</StackPanel> 


Here, each Button is a child element of StackPanel. This is a streamlined and intuitive markup that omits two 
tags for two different reasons. 

• Omitted StackPanel.Children property element: StackPanel derives from Panel. Panel defines 
Panel.Children as its XAML content property. 

• Omitted UlElementCollection object element: The Panel.Children property takes the type 
UlElementCollection, which implements IList. The collection's element tag can be omitted, based on the 
XAML rules for processing collections such as IList. (In this case, UlElementCollection actually cannot be 
instantiated because it does not expose a parameterless constructor, and that is why the 
UlElementCollection object element is shown commented out). 


<StackPanel> 

<StackPanel.Children) 

<!--<UIElementCollection>--> 
<Button>First Button</Button> 
<Button>Second Button</Button> 
<!--</UIElementCollection>--> 
</StackPanel.Children) 
</StackPanel) 


Attribute syntax (events) 

Attribute syntax can also be used for members that are events rather than properties. In this case, the 
attribute's name is the name of the event. In the WPF implementation of events for XAML, the attribute's value 
is the name of a handler that implements that event's delegate. For example, the following markup assigns a 
handler for the Click event to a Button created in markup: 

<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="ExampleNamespace.ExamplePage") 

<Button Click="Button_Click" )Click Me!</Button) 

</Page) 


There is more to events and XAML in WPF than Just this example of the attribute syntax. For example, you 
might wonder what the ciickHandier referenced here represents and how it is defined. This will be explained 
in the upcoming Events and XAML code-behind section of this article. 

Case an(d white space in XAML 

In general, XAML is case-sensitive. For purposes of resolving backing types, WPF XAML is case-sensitive by the 
same rules that the CLR is case-sensitive. Object elements, property elements, and attribute names must all be 
specified by using the sensitive casing when compared by name to the underlying type in the assembly, or to a 
member of a type. XAML language keywords and primitives are also case-sensitive. Values are not always 
case-sensitive. Case sensitivity for values will depend on the type converter behavior associated with the 






property that takes the value, or the property value type. For example, properties that take the Boolean type 
can take either true or True as equivalent values, but only because the native WPF XAML parser type 
conversion for string to Boolean already permits these as equivalents. 

WPF XAML processors and serializers will ignore or drop all nonsignificant white space, and will normalize any 
significant white space. This is consistent with the default white-space behavior recommendations of the XAML 
specification. This behavior is only of consequence when you specify strings within XAML content properties. 

In simplest terms, XAML converts space, linefeed, and tab characters into spaces, and then preserves one space 
if found at either end of a contiguous string. The full explanation of XAML white-space handling is not covered 
in this article. For more information, see White space processing in XAML. 

Markup extensions 

Markup extensions are a XAML language concept. When used to provide the value of an attribute syntax, curly 
braces ( { and } ) indicate a markup extension usage. This usage directs the XAML processing to escape from 
the general treatment of attribute values as either a literal string or a string-convertible value. 

The most common markup extensions used in WPF app programming are Binding , used for data binding 
expressions, and the resource references staticResource and DynamicResource . By using markup extensions, 
you can use attribute syntax to provide values for properties even if that property does not support an 
attribute syntax in general. Markup extensions often use intermediate expression types to enable features such 
as deferring values or referencing other objects that are only present at run-time. 

For example, the following markup sets the value of the Style property using attribute syntax. The Style 
property takes an instance of the Style class, which by default could not be instantiated by an attribute syntax 
string. But in this case, the attribute references a particular markup extension, staticResource . When that 
markup extension is processed, it returns a reference to a style that was previously instantiated as a keyed 
resource in a resource dictionary. 

<Page.Resources> 

<SolidColorBrush x:Key="MyBrush" Color="Gold"/> 

<Style TargetType="Border" x:Key="PageBackground"> 

<Setter Property="Bacl<ground" Value="Blue"/> 

</Style> 


</Page.Resources> 

<StackPanel> 

<Border Style="{StaticResource PageBackground}"> 

</Border> 

</StackPanel> 

For a reference listing of all markup extensions for XAML implemented specifically in WPF, see WPF XAML 
Extensions. For a reference listing of the markup extensions that are defined by System.XamI and are more 
widely available for .NET Core XAML implementations, see XAML Namespace (x:) Language Features. For more 
information about markup extension concepts, see Markup Extensions and WPF XAML. 

Type converters 

In the XAML Syntax in Brief section, it was stated that the attribute value must be able to be set by a string. The 
basic, native handling of how strings are converted into other object types or primitive values is based on the 
String type itself, in addition to native processing for certain types such as DateTime or Uri. But many WPF 
types or members of those types extend the basic string attribute processing behavior in such a way that 








instances of more complex object types can be specified as strings and attributes. 

The Thickness structure is an example of a type that has a type conversion enabled for XAML usages. Thickness 
indicates measurements within a nested rectangle and is used as the value for properties such as Margin. By 
placing a type converter on Thickness, all properties that use a Thickness are easier to specify in XAML because 
they can be specified as attributes. The following example uses a type conversion and attribute syntax to 
provide a value for a Margin: 

<Button Margin="10,20jl0j30" Content="Click me"/> 

The previous attribute syntax example is equivalent to the following more verbose syntax example, where the 
Margin is instead set through property element syntax containing a Thickness object element. The four key 
properties of Thickness are set as attributes on the new instance: 

<Button Content="Clicl< me"> 

<Button.Margin> 

<Thicl<ness Left="10" Top="20" Right="10" Bottom="30"/> 

</Button.Mar'gin> 

</Button> 



For more information on type conversion, see TypeConverters and XAML. 

XAML root elements and XAML namespaces 

A XAML file must have only one root element, in order to be both a well-formed XML file and a valid XAML file. 
For typical WPF scenarios, you use a root element that has a prominent meaning in the WPF app model (for 
example. Window or Page for a page, ResourceDictionary for an external dictionary, or Application for the app 
definition). The following example shows the root element of a typical XAML file for a WPF page, with the root 
element of Page. 

<Page 

xmlns="http: //schemas. micnosoft. com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml"> 

</Page> 

The root element also contains the attributes xmlns and xmlns:x . These attributes indicate to a XAML 
processor which XAML namespaces contain the type definitions for backing types that the markup will 
reference as elements. The xmlns attribute specifically indicates the default XAML namespace. Within the 
default XAML namespace, object elements in the markup can be specified without a prefix. For most WPF app 
scenarios, and for almost all of the examples given in the WPF sections of the SDK, the default XAML 
namespace is mapped to the WPF namespace http://schemas.microsoft.com/winfx/2006/xami/presentation .The 
xmins:x attribute indicates an additional XAML namespace, which maps the XAML language namespace 
http://schemas.micnosoft.com/winfx/2006/xaml . 

This usage of xmlns to define a scope for usage and mapping of a namescope is consistent with the XML 1.0 









specification. XAML namescopes are different from XML namescopes only in that a XAML namescope also 
implies something about how the namescope's elements are backed by types when it comes to type resolution 
and parsing the XAML. 

The xmins attributes are only strictly necessary on the root element of each XAML file, xmins definitions will 
apply to all descendant elements of the root element (this behavior is again consistent with the XML 1.0 
specification for xmins.) xmins attributes are also permitted on other elements underneath the root, and 
would apply to any descendant elements of the defining element. However, frequent definition or redefinition 
of XAML namespaces can result in a XAML markup style that is difficult to read. 

The WPF implementation of its XAML processor includes an infrastructure that has awareness of the WPF core 
assemblies. The WPF core assemblies are known to contain the types that support the WPF mappings to the 
default XAML namespace. This is enabled through configuration that is part of your project build file and the 
WPF build and project systems. Therefore, declaring the default XAML namespace as the default xmins is all 
that is necessary in order to reference XAML elements that come from WPF assemblies. 

The x: prefix 

In the previous root element example, the prefix x: was used to map the XAML namespace 
http://schemas.microsoft.com/winfx/2006/xami , which is the dedicated XAML namespace that supports XAML 
language constructs. This x: prefix is used for mapping this XAML namespace in the templates for projects, in 
examples, and in documentation throughout this SDK. The XAML namespace for the XAML language contains 
several programming constructs that you will use frequently in your XAML. The following is a listing of the 
most common x: prefix programming constructs you will use: 

• x:Key: Sets a unique key for each resource in a ResourceDictionary (or similar dictionary concepts in 
other frameworks). x:Key will probably account for 90 percent of the x: usages you will see in a 
typical WPF app's markup. 

• x:Class; Specifies the CLR namespace and class name for the class that provides code-behind for a XAML 
page. You must have such a class to support code-behind per the WPF programming model, and 
therefore you almost always see x: mapped, even if there are no resources. 

• x:Name; Specifies a run-time object name for the instance that exists in run-time code after an object 
element is processed. In general, you will frequently use a WPF-defined equivalent property for x:Name. 
Such properties map specifically to a CLR backing property and are thus more convenient for app 
programming, where you frequently use run-time code to find the named elements from initialized 
XAML. The most common such property is FrameworkElement.Name. You might still use x:Name when 
the equivalent WPF framework-level Name property is not supported in a particular type. This occurs in 
certain animation scenarios. 

• x:Static: Enables a reference that returns a static value that is not otherwise a XAML-compatible 
property. 

• x:Type: Constructs a Type reference based on a type name. This is used to specify attributes that take 
Type, such as Style.TargetType, although frequently the property has native string-to-Type conversion in 
such a way that the x:Type markup extension usage is optional. 

There are additional programming constructs in the x: prefix/XAML namespace, which are not as common. 
For details, see XAML Namespace (x:) Language Features. 

Custom prefixes and custom types in XAML 

For your own custom assemblies, or for assemblies outside the WPF core of PresentationCore, 
PresentationFramework and WindowsBase, you can specify the assembly as part of a custom xmins 
mapping. You can then reference types from that assembly in your XAML, so long as that type is correctly 













implemented to support the XAML usages you are attempting. 



knows which XAML namespace contains the type, and therefore where the backing assembly is that contains 
the type definition. 

<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

xmlns:custom="clr-namespace:NumericLlpDownCustomControl;assembly=CustomLibrary" 

> 

cStackPanel Name="LayoutRoot"> 

<custom:NumericUpDown Name="numericCtrll" Width="100" Height="60"/> 

</StackPanel> 

</Page> 


For more information about custom types in XAML, see XAML and Custom Classes for WPF. 

For more information about how XML namespaces and code namespaces in assemblies are related, see XAML 
Namespaces and Namespace Mapping for WPF XAML. 

Events and XAML code-behind 

Most WPF apps consist of both XAML markup and code-behind. Within a project, the XAML is written as a 
■ xami file, and a CLR language such as Microsoft Visual Basic or C# is used to write a code-behind file. When 
a XAML file is markup compiled as part of the WPF programming and application models, the location of the 
XAML code-behind file for a XAML file is identified by specifying a namespace and class as the xrciass 
attribute of the root element of the XAML. 

In the examples so far, you have seen several buttons, but none of these buttons had any logical behavior 
associated with them yet. The primary application-level mechanism for adding a behavior for an object 
element is to use an existing event of the element class, and to write a specific handler for that event that is 
invoked when that event is raised at run-time. The event name and the name of the handler to use are 
specified in the markup, whereas the code that implements your handler is defined in the code-behind. 

<Page 

xmlns="http: //schemas. microsoft. com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="ExampleNamespace.ExamplePage"> 

<Button Click="Button_Click" >Click Me!</Button> 

</Page> 









any compiled XAML file, by deriving a class from the root element type. When you provide code-behind that 
also defines the same partial class, the resulting code is combined within the same namespace and class of the 
compiled app. 

For more information about requirements for code-behind programming in WPF, see Code-behind, Event 
Handler, and Partial Class Requirements in WPF. 

If you do not want to create a separate code-behind file, you can also inline your code in a XAML file. However, 
inline code is a less versatile technique that has substantial limitations. For more informaiton, see Code-Behind 
and XAML in WPF. 

Routed events 

A particular event feature that is fundamental to WPF is a routed event. Routed events enable an element to 
handle an event that was raised by a different element, as long as the elements are connected through a tree 
relationship. When specifying event handling with a XAML attribute, the routed event can be listened for and 
handled on any element, including elements that do not list that particular event in the class members table. 
This is accomplished by qualifying the event name attribute with the owning class name. For instance, the 
parent stackPanei in the ongoing stackPanei / Button example could register a handler for the child 
element button's Click event by specifying the attribute Button.Click on the stackPanei object element, with 
your handler name as the attribute value. For more information, see Routed Events Overview. 

XAML named elements 

By default, the object instance that is created in an object graph by processing a XAML object element does not 
possess a unique identifier or object reference. In contrast, if you call a constructor in code, you almost always 
use the constructor result to set a variable to the constructed instance, so that you can reference the instance 
later in your code. In order to provide standardized access to objects that were created through a markup 
definition, XAML defines the x:Name attribute. You can set the value of the x:Name attribute on any object 
element. In your code-behind, the identifier you choose is equivalent to an instance variable that refers to the 
constructed instance. In all respects, named elements function as if they were object instances (the name 
references that instance), and your code-behind can reference the named elements to handle run-time 
interactions within the app. This connection between instances and variables is accomplished by the WPF 
XAML markup compiler, and more specifically involve features and patterns such as InitializeComponent that 
will not be discussed in detail in this article. 












WPF framework-level XAML elements inherit a Name property, which is equivalent to the XAML defined 
x:Name attribute. Certain other classes also provide property-level equivalents for x:Name , which is also 
generally defined as a Name property. Generally speaking, if you cannot find a Name property in the members 
table for your chosen element/type, use x:Name instead. The x:Name values will provide an identifier to a 
XAML element that can be used at run-time, either by specific subsystems or by utility methods such as 
FindName. 

The following example sets Name on a StackPanel element. Then, a handler on a Button within that StackPanel 
references the StackPanel through its instance reference buttonContainer as set by Name. 

<StackPanel Name="buttonContainer"> 

<Button Click="RemoveThis">Clicl< to remove this button</Button> 

</StackPanel> 

void RemoveThis(object senderj RoutedEventArgs e) 

{ 

FrameworkElement fe = e.Source as FrameworkElement; 
if (buttonContainer.Children.Contains(fe)) 

{ 

buttonContainer.Children.Remove(fe); 

} 

} 


Private Sub RemoveThis(ByVal sender As System.Object, ByVal e As System.Windows.RoutedEventArgs) 

Dim fe As FrameworkElement = e.Source 
If (buttonContainer.Children.Contains(fe)) Then 
buttonContainer.Children.Remove(fe) 

End If 
End Sub 

Just like a variable, the XAML name for an instance is governed by a concept of scope, so that names can be 
enforced to be unique within a certain scope that is predictable. The primary markup that defines a page 
denotes one unique XAML namescope, with the XAML namescope boundary being the root element of that 
page. However, other markup sources can interact with a page at run-time, such as styles or templates within 
styles, and such markup sources often have their own XAML namescopes that do not necessarily connect with 
the XAML namescope of the page. For more information on x:Name and XAML namescopes, see Name, 
x:Name Directive, or WPF XAML Namescopes. 

Attached properties and attached events 

XAML specifies a language feature that enables certain properties or events to be specified on any element, 
regardless of whether the property or event exists in the type's definitions for the element it is being set on. 
The properties version of this feature is called an attached property, the events version is called an attached 
event. Conceptually, you can think of attached properties and attached events as global members that can be 
set on any XAML element/object instance. However, that element/class or a larger infrastructure must support 
a backing property store for the attached values. 

Attached properties in XAML are typically used through attribute syntax. In attribute syntax, you specify an 
attached property in the form ownenlype.propertyName . 

Superficially, this resembles a property element usage, but in this case the owneriype you specify is always a 
different type than the object element where the attached property is being set. owneriype is the type that 













provides the accessor methods that are required by a XAML processor in order to get or set the attached 
property value. 

The most common scenario for attached properties is to enable child elements to report a property value to 
their parent element. 

The following example illustrates the DockPanel.Dock attached property. The DockPanel class defines the 
accessors for DockPanel.Dock and therefore owns the attached property. The DockPanel class also includes 
logic that iterates its child elements and specifically checks each element for a set value of DockPanel.Dock. If a 
value is found, that value is used during layout to position the child elements. Use of the DockPanel.Dock 
attached property and this positioning capability is in fact the motivating scenario for the DockPanel class. 

<DockPanel> 

<Button DockPanel.Docl<="Left" Width="100" Height="20">I am on the left</Button> 

<Button DockPanel.Dock="Right" Width="100" Height="20">I am on the right</Button> 

</DockPanel> 

In WPF, most or all the attached properties are also implemented as dependency properties. For more 
information, see Attached Properties Overview. 

Attached events use a similar owneniype.eventName form of attribute syntax. Just like the non-attached events, 
the attribute value for an attached event in XAML specifies the name of the handler method that is invoked 
when the event is handled on the element. Attached event usages in WPF XAML are less common. For more 
information, see Attached Events Overview. 

Base types and XAML 

Underlying WPF XAML and its XAML namespace is a collection of types that correspond to CLR objects in 
addition to markup elements for XAML. However, not all classes can be mapped to elements. Abstract classes, 
such as ButtonBase, and certain non-abstract base classes, are used for inheritance in the CLR objects model. 
Base classes, including abstract ones, are still important to XAML development because each of the concrete 
XAML elements inherits members from some base class in its hierarchy. Often these members include 
properties that can be set as attributes on the element, or events that can be handled. FrameworkElement is 
the concrete base Ul class of WPF at the WPF framework level. When designing Ul, you will use various shape, 
panel, decorator, or control classes, which all derive from FrameworkElement. A related base class, 
FrameworkContentElement, supports document-oriented elements that work well for a flow layout 
presentation, using APIs that deliberately mirror the APIs in FrameworkElement. The combination of attributes 
at the element level and a CLR object model provides you with a set of common properties that are settable on 
most concrete XAML elements, regardless of the specific XAML element and its underlying type. 

XAML security 

XAML is a markup language that directly represents object instantiation and execution. Therefore, elements 
created in XAML have the same ability to interact with system resources (network access, file system 10, for 
example) as the equivalent generated code does. XAML loaded in to a fully trusted app has the same access to 
the system resources as the hosting app does. 

Code Access Security (CAS) in WPF 

This section only applies to .NET Framework. WPF for .NET Core doesn't support CAS. For more 
information, see Code Access Security differences. 

WPF for .NET Framework supports Code Access Security (CAS). This means that WPF content running in the 
internet zone has reduced execution permissions. "Loose XAML" (pages of noncompiled XAML interpreted at 
load time by a XAML viewer) and XBAP are usually run in this internet zone and use the same permission set. 
However, XAML loaded in to a fully trusted application has the same access to the system resources as the 




hosting application does. For more information, see WPF Partial Trust Security. 


Loading XAML from code 

XAML can be used to define all of the Ul, but it is sometimes also appropriate to define just a piece of the Ul in 
XAML. This capability could be used to enable partial customization, local storage of information, using XAML 
to provide a business object, or a variety of possible scenarios. The key to these scenarios is the XamIReader 
class and its Load method. The input is a XAML file, and the output is an object that represents all of the run¬ 
time tree of objects that was created from that markup. You then can insert the object to be a property of 
another object that already exists in the app. So long as the property is an appropriate property in the content 
model that has eventual display capabilities and that will notify the execution engine that new content has 
been added into the app, you can modify a running app's contents easily by loading in XAML. For .NET 
Framework, this capability is generally only available in full-trust applications, because of the obvious security 
implications of loading files into applications as they run. 

See also 
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This topic defines the terms that are used to describe the elements of XAML syntax. These terms are used 
frequently throughout the remainder of this documentation, both for WPF documentation specifically and for the 
other frameworks that use XAML or the basic XAML concepts enabled by the XAML language support at the 
System.XamI level. This topic expands on the basic terminology introduced in the topic XAML Overview (WPF). 

The XAML Language Specification 

The XAML syntax terminology defined here is also defined or referenced within the XAML language specification. 
XAML is a language based on XML and follows or expands upon XML structural rules. Some of the terminology is 
shared from or is based on the terminology commonly used when describing the XML language or the XML 
document object model. 

For more information about the XAML language specification, download [MS-XAML] from the Microsoft 
Download Center. 


XAML and CLR 


XAML is a markup language. The common language runtime (CLR), as implied by its name, enables runtime 
execution. XAML is not by itself one of the common languages that is directly consumed by the CLR runtime. 
Instead, you can think of XAML as supporting its own type system. The particular XAML parsing system that is 
used by WPF is built on the CLR and the CLR type system. XAML types are mapped to CLR types to instantiate a 
run time representation when the XAML for WPF is parsed. For this reason, the remainder of discussion of syntax 
in this document will include references to the CLR type system, even though the equivalent syntax discussions in 
the XAML language specification do not. (Per the XAML language specification level, XAML types could be 
mapped to any other type system, which does not have to be the CLR, but that would require the creation and 
use of a different XAML parser.) 

Members of Types and Class Inheritance 

Properties and events as they appear as XAML members of a WPF type are often inherited from base types. For 
example, consider this example: <Button Background="Biue" .../>. The Background property is not an 
immediately declared property on the Button class, if you were to look at the class definition, reflection results, or 
the documentation. Instead, Background is inherited from the base Control class. 

The class inheritance behavior of WPF XAML elements is a significant departure from a schema-enforced 
interpretation of XML markup. Class inheritance can become complex, particularly when intermediate base 
classes are abstract, or when interfaces are involved. This is one reason that the set of XAML elements and their 
permissible attributes is difficult to represent accurately and completely using the schema types that are typically 
used for XML programming, such as DTD or XSD format. Another reason is that extensibility and type-mapping 
features of the XAML language itself preclude completeness of any fixed representation of the permissible types 
and members. 

Object Element Syntax 

Object elementsyntaxis the XAML markup syntax that instantiates a CLR class or structure by declaring an XML 
element. This syntax resembles the element syntax of other markup languages such as HTML. Object element 
syntax begins with a left angle bracket (<), followed immediately by the type name of the class or structure being 
instantiated. Zero or more spaces can follow the type name, and zero or more attributes may also be declared on 





the object element, with one or more spaces separating each attribute name="value" pair. Finally, one of the 
following must be true: 

• The element and tag must be closed by a forward slash (/) followed immediately by a right angle bracket 
(>). 

• The opening tag must be completed by a right angle bracket (>). Other object elements, property 
elements, or inner text, can follow the opening tag. Exactly what content may be contained here is typically 
constrained by the object model of the element. The equivalent closing tag for the object element must 
also exist, in proper nesting and balance with other opening and closing tag pairs. 

XAML as implemented by .NET has a set of rules that map object elements into types, attributes into properties or 
events, and XAML namespaces to CLR namespaces plus assembly. For WPF and .NET, XAML object elements map 
to .NET types as defined in referenced assemblies, and the attributes map to members of those types. When you 
reference a CLR type in XAML, you have access to the inherited members of that type as well. 

For example, the following example is object element syntax that instantiates a new instance of the Button class, 
and also specifies a Name attribute and a value for that attribute: 

<Button Name="CheckoutButton"/> 

The following example is object element syntax that also includes XAML content property syntax. The inner text 
contained within will be used to set the TextBox XAML content property. Text. 

<TextBox>This is a Text Box</TextBox> 

Content Models 

A class might support a usage as a XAML object element in terms of the syntax, but that element will only 
function properly in an application or page when it is placed in an expected position of an overall content model 
or element tree. For example, a Menultem should typically only be placed as a child of a MenuBase derived class 
such as Menu. Content models for specific elements are documented as part of the remarks on the class pages 
for controls and other WPF classes that can be used as XAML elements. 

Properties of Object Elements 

Properties in XAML are set by a variety of possible syntaxes. Which syntax can be used for a particular property 
will vary, based on the underlying type system characteristics of the property that you are setting. 

By setting values of properties, you add features or characteristics to objects as they exist in the run time object 
graph. The initial state of the created object from a object element is based on the parameterless constructor 
behavior. Typically, your application will use something other than a completely default instance of any given 
object. 

Attribute Syntax (Properties) 

Attribute syntax is the XAML markup syntax that sets a value for a property by declaring an attribute on an 
existing object element. The attribute name must match the CLR member name of the property of the class that 
backs the relevant object element. The attribute name is followed by an assignment operator (=). The attribute 
value must be a string enclosed within quotes. 




NOTE 

You can use alternating quotes to place a literal quotation mark within an attribute. For instance you can use single quotes 
as a means to declare a string that contains a double quote character within it. Whether you use single or double quotes, 
you should use a matching pair for opening and closing the attribute value string. There are also escape sequences or 
other techniques available for working around character restrictions imposed by any particular XAML syntax. See XML 
Character Entities and XAML. 


In order to be set through attribute syntax, a property must be public and must be writeable. The value of the 
property in the backing type system must be a value type, or must be a reference type that can be instantiated or 
referenced by a XAML processor when accessing the relevant backing type. 

For WPF XAML events, the event that is referenced as the attribute name must be public and have a public 
delegate. 

The property or event must be a member of the class or structure that is instantiated by the containing object 
element. 

Processing of Attribute Values 

The string value contained within the opening and closing quotation marks is processed by a XAML processor. 

For properties, the default processing behavior is determined by the type of the underlying CLR property. 

The attribute value is filled by one of the following, using this processing order: 

1. If the XAML processor encounters a curly brace, or an object element that derives from MarkupExtension, 
then the referenced markup extension is evaluated first rather than processing the value as a string, and 
the object returned by the markup extension is used as the value. In many cases the object returned by a 
markup extension will be a reference to an existing object, or an expression that defers evaluation until run 
time, and is not a newly instantiated object. 

2. If the property is declared with an attributed TypeConverter, or the value type of that property is declared 
with an attributed TypeConverter, the string value of the attribute is submitted to the type converter as a 
conversion input, and the converter will return a new object instance. 

3. If there is no TypeConverter, a direct conversion to the property type is attempted. This final level is a 
direct conversion at the parser-native value between XAML language primitive types, or a check for the 
names of named constants in an enumeration (the parser then accesses the matching values). 

Enumeration Attribute Values 

Enumerations in XAML are processed intrinsically by XAML parsers, and the members of an enumeration should 
be specified by specifying the string name of one of the enumeration's named constants. 

For nonflag enumeration values, the native behavior is to process the string of an attribute value and resolve it to 
one of the enumeration values. You do not specify the enumeration in the format Enumeration. Value, as you do in 
code. Instead, you specify only Value, and Enumeration is inferred by the type of the property you are setting. If 
you specify an attribute in the Enumeration.Valueiorm, it will not resolve correctly. 

For flagwise enumerations, the behavior is based on the Enum.Parse method. You can specify multiple values for 
a flagwise enumeration by separating each value with a comma. However, you cannot combine enumeration 
values that are not flagwise. For instance, you cannot use the comma syntax to attempt to create a Trigger that 
acts on multiple conditions of a nonflag enumeration: 



<!--This will not compilej because Visibility is not a flagwise enumeration.--> 

<Trigger Property="Visibility" Value="CollapsedjHidden"> 

<Setter ... /> 

</Trigger> 

Flagwise enumerations that support attributes that are settable in XAML are rare in WPF. However, one such 
enumeration is StyleSimulations. You could, for instance, use the comma-delimited flagwise attribute syntax to 
modify the example provided in the Remarks for the Glyphs class; styiesimuiations = "Boidsimuiation" could 
become styiesimuiations = "Boidsimuiation,itaiicsimuiation" . KeyBinding.Modifiers is another property where 
more than one enumeration value can be specified. However, this property happens to be a special case, because 
the ModifierKeys enumeration supports its own type converter. The type converter for modifiers uses a plus sign 
(+) as a delimiter rather than a comma (,). This conversion supports the more traditional syntax to represent key 
combinations in Microsoft Windows programming, such as "Ctrl+Alt". 

Properties and Event Member Name References 

When specifying an attribute, you can reference any property or event that exists as a member of the CLR type 
you instantiated for the containing object element. 

Or, you can reference an attached property or attached event, independent of the containing object element. 
(Attached properties are discussed in an upcoming section.) 

You can also name any event from any object that is accessible through the default namespace by using a 
typeName.eventpar^\a\\)/ qualified name; this syntax supports attaching handlers for routed events where the 
handler is intended to handle events routing from child elements, but the parent element does not also have that 
event in its members table. This syntax resembles an attached event syntax, but the event here is not a true 
attached event. Instead, you are referencing an event with a qualified name. For more information, see Routed 
Events Overview. 

For some scenarios, property names are sometimes provided as the value of an attribute, rather than the 
attribute name. That property name can also include qualifiers, such as the property specified in the form 
ownerType.dependencyPropertyName. This scenario is common when writing styles or templates in XAML. The 
processing rules for property names provided as an attribute value are different, and are governed by the type of 
the property being set or by the behaviors of particular WPF subsystems. For details, see Styling and Templating. 

Another usage for property names is when an attribute value describes a property-property relationship. This 
feature is used for data binding and for storyboard targets, and is enabled by the PropertyPath class and its type 
converter. For a more complete description of the lookup semantics, see PropertyPath XAML Syntax. 

Property Element Syntax 

Property elementsyntaxis a syntax that diverges somewhat from the basic XML syntax rules for elements. In 
XML, the value of an attribute is a de facto string, with the only possible variation being which string encoding 
format is being used. In XAML, you can assign other object elements to be the value of a property. This capability 
is enabled by the property element syntax. Instead of the property being specified as an attribute within the 
element tag, the property is specified using an opening element tag in elementTypeName.propertyNameform, 
the value of the property is specified within, and then the property element is closed. 

Specifically, the syntax begins with a left angle bracket (<), followed immediately by the type name of the class or 
structure that the property element syntax is contained within. This is followed immediately by a single dot (.), 
then by the name of a property, then by a right angle bracket (>). As with attribute syntax, that property must 
exist within the declared public members of the specified type. The value to be assigned to the property is 
contained within the property element. Typically, the value is given as one or more object elements, because 
specifying objects as values is the scenario that property element syntax is intended to address. Finally, an 





equivalent closing tag specifying the same e/ementTypeName.propertyNamecomb\nat\or\ must be provided, in 
proper nesting and balance with other element tags. 

For example, the following is property element syntax for the ContextMenu property of a Button. 

<Button> 

<Button.ContextMenu> 

<ContextMenu> 

<MenuItem Header'="l">Fir'st item</MenuItem> 

<MenuItem Header'="2">Second item</MenuItem> 

</ContextMenu> 

</Button.ContextMenu> 

Right-click me!</Button> 

The value within a property element can also be given as inner text, in cases where the property type being 
specified is a primitive value type, such as String, or an enumeration where a name is specified. These two usages 
are somewhat uncommon, because each of these cases could also use a simpler attribute syntax. One scenario 
for filling a property element with a string is for properties that are not the XAML content property but still are 
used for representation of Ul text, and particular white-space elements such as linefeeds are required to appear 
in that Ul text. Attribute syntax cannot preserve linefeeds, but property element syntax can, so long as significant 
white-space preservation is active (for details, see White space processing in XAML). Another scenario is so that 
x:Uid Directive can be applied to the property element and thus mark the value within as a value that should be 
localized in the WPF output BAML or by other techniques. 

A property element is not represented in the WPF logical tree. A property element is just a particular syntax for 
setting a property, and is not an element that has an instance or object backing it. (For details on the logical tree 
concept, see Trees in WPF.) 

For properties where both attribute and property element syntax are supported, the two syntaxes generally have 
the same result, although subtleties such as white-space handling can vary slightly between syntaxes. 

Collection Syntax 

The XAML specification requires XAML processor implementations to identify properties where the value type is 
a collection. The general XAML processor implementation in .NET is based on managed code and the CLR, and it 
identifies collection types through one of the following: 

• Type implements IList. 

• Type implements IDictionary. 

• Type derives from Array (for more information about arrays in XAML, see x:Array Markup Extension.) 

If the type of a property is a collection, then the inferred collection type does not need to be specified in the 
markup as an object element. Instead, the elements that are intended to become the items in the collection are 
specified as one or more child elements of the property element. Each such item is evaluated to an object during 
loading and added to the collection by calling the Add method of the implied collection. For example, the 
Triggers property of Style takes the specialized collection type TriggerCollection, which implements IList. It is not 
necessary to instantiate a TriggerCollection object element in the markup. Instead, you specify one or more 
Trigger items as elements within the style.Triggers property element, where Trigger (or a derived class) is the 
type expected as the item type for the strongly typed and implicit TriggerCollection. 




<Style x:Key="SpecialButton" TargetType="{x:Type Button}"> 
<Style.Triggers> 

<Trigger Property="Button.IsMouseOver" Value="true"> 
<Setter Property = "Background" \/alue="Red"/> 
</Trigger> 

<Trigger Property="Button.IsPressed" Value="true"> 
<Setter Property = "Foreground" \/alue="Green"/> 
</Trigger> 

</Style.Triggers> 

</Style> 


A property may be both a collection type and the XAML content property for that type and derived types, which 
is discussed in the next section of this topic. 

An implicit collection element creates a member in the logical tree representation, even though it does not 
appear in the markup as an element. Usually the constructor of the parent type performs the instantiation for the 
collection that is one of its properties, and the initially empty collection becomes part of the object tree. 


NOTE 

The generic list and dictionary interfaces (IList<T> and IDictionary<TKey,TValue>) are not supported for collection 
detection. However, you can use the List<T> class as a base class, because it implements I List directly, or 
Dictionary<TKey,TValue> as a base class, because it implements IDictionary directly. 


In the .NET Reference pages for collection types, this syntax with the deliberate omission of the object element for 
a collection is occasionally noted in the XAML syntax sections as Implicit Collection Syntax. 

With the exception of the root element, every object element in a XAML file that is nested as a child element of 
another element is really an element that is one or both of the following cases: a member of an implicit collection 
property of its parent element, or an element that specifies the value of the XAML content property for the parent 
element (XAML content properties will be discussed in an upcoming section). In other words, the relationship of 
parent elements and child elements in a markup page is really a single object at the root, and every object 
element beneath the root is either a single instance that provides a property value of the parent, or one of the 
items within a collection that is also a collection-type property value of the parent. This single-root concept is 
common with XML, and is frequently reinforced in the behavior of APIs that load XAML such as Load. 

The following example is a syntax with the object element for a collection (GradientStopCollection) specified 
explicitly. 

<LinearGradientBrush) 

<LinearGradientBrush.GradlentStops> 

<GradientStopCollection> 

<GradientStop Offset="0.0" Color="Red" /> 

<GradientStop Offset="1.0" Color="Blue" /> 

</GradientStopCollection) 

</tinearGradientBrush.GradientStops) 

</tinearGradientBrush) 


Note that it is not always possible to explicitly declare the collection. For instance, attempting to declare 
TriggerCollection explicitly in the previously shown Triggers example would fail. Explicitly declaring the collection 
requires that the collection class must support a parameterless constructor, and TriggerCollection does not have a 
parameterless constructor. 

XAML Content Properties 

XAML content syntax is a syntax that is only enabled on classes that specify the ContentPropertyAttribute as part 





of their class declaration. The ContentPropertyAttribute references the property name that is the content 
property for that type of element (including derived classes). When processed by a XAML processor, any child 
elements or inner text that are found between the opening and closing tags of the object element will be 
assigned to be the value of the XAML content property for that object. You are permitted to specify explicit 
property elements for the content property, but this usage is not generally shown in the XAML syntax sections in 
the .NET reference. The explicit/verbose technique has occasional value for markup clarity or as a matter of 
markup style, but usually the intent of a content property is to streamline the markup so that elements that are 
intuitively related as parent-child can be nested directly. Property element tags for other properties on an 
element are not assigned as "content" per a strict XAML language definition; they are processed previously in the 
XAML parser's processing order and are not considered to be "content". 

XAML Content Property Values Must Be Contiguous 

The value of a XAML content property must be given either entirely before or entirely after any other property 
elements on that object element. This is true whether the value of a XAML content property is specified as a 
string, or as one or more objects. For example, the following markup does not parse: 

<Button>I am a 

<Button. Background >Blue</Button.Backgr'ound> 

blue button</Button> 


This is illegal essentially because if this syntax were made explicit by using property element syntax for the 
content property, then the content property would be set twice: 

<Button> 

<Button.Content>I am a </Button.Contents 
<Button.Background>Blue</Button.Backgrounds 
<Button.Contents blue button</Button.Contents 
</Buttons 


A similarly illegal example is if the content property is a collection, and child elements are interspersed with 
property elements: 

<StackPanels 

<ButtonsThis examplec/Buttons 
<StackPanel.Resourcess 

<SolidColorBrush x:Key="BlueBrush" Color="Blue"/s 
</StackPanel.Resourcess 
<Buttons... is illegal XAML</Buttons 
</StackPanels 


Content Properties and Collection Syntax Combined 

In order to accept more than a single object element as content, the type of the content property must specifically 
be a collection type. Similar to property element syntax for collection types, a XAML processor must identify 
types that are collection types. If an element has a XAML content property and the type of the XAML content 
property is a collection, then the implied collection type does not need to be specified in the markup as an object 
element and the XAML content property does not need to be specified as a property element. Therefore the 
apparent content model in the markup can now have more than one child element assigned as the content. The 
following is content syntax for a Panel derived class. All Panel derived classes establish the XAML content 
property to be Children, which requires a value of type UlElementCollection. 




<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

cStackPaneIx 

<Button>Button l</Button> 

<Button>Button 2</Button> 

<Button>Button 3</Button> 

</StackPanel> 

</Page> 

Note that neither the property element for Children nor the element for the UlElementCollection is required in 
the markup. This is a design feature of XAML so that recursively contained elements that define a Ul are more 
intuitively represented as a tree of nested elements with immediate parent-child element relationships, without 
intervening property element tags or collection objects. In fact, UlElementCollection cannot be specified explicitly 
in markup as an object element, by design. Because its only intended use is as an implicit collection, 
UlElementCollection does not expose a public parameterless constructor and thus cannot be instantiated as an 
object element. 

Mixing Property Elements and Object Elements in an Object with a Content Property 

The XAML specification declares that a XAML processor can enforce that object elements that are used to fill the 
XAML content property within an object element must be contiguous, and must not be mixed. This restriction 
against mixing property elements and content is enforced by the WPF XAML processors. 

You can have a child object element as the first immediate markup within an object element. Then you can 
introduce property elements. Or, you can specify one or more property elements, then content, then more 
property elements. But once a property element follows content, you cannot introduce any further content, you 
can only add property elements. 

This content / property element order requirement does not apply to inner text used as content. However, it is still 
a good markup style to keep inner text contiguous, because significant white space will be difficult to detect 
visually in the markup if property elements are interspersed with inner text. 

XAML Namespaces 

None of the preceding syntax examples specified a XAML namespace other than the default XAML namespace. In 
typical WPF applications, the default XAML namespace is specified to be the WPF namespace. You can specify 
XAML namespaces other than the default XAML namespace and still use similar syntax. But then, anywhere 
where a class is named that is not accessible within the default XAML namespace, that class name must be 
preceded with the prefix of the XAML namespace as mapped to the corresponding CLR namespace. For example, 
<custom:Exampie/> is object element Syntax to instantiate an instance of the Example class, where the CLR 
namespace containing that class (and possibly the external assembly information that contains backing types) 
was previously mapped to the custom prefix. 

For more information about XAML namespaces, see XAML Namespaces and Namespace Mapping for WPF 
XAML. 

Markup Extensions 

XAML defines a markup extension programming entity that enables an escape from the normal XAML processor 
handling of string attribute values or object elements, and defers the processing to a backing class. The character 
that identifies a markup extension to a XAML processor when using attribute syntax is the opening curly brace ({), 
followed by any character other than a closing curly brace (}). The first string following the opening curly brace 
must reference the class that provides the particular extension behavior, where the reference may omit the 
substring "Extension" if that substring is part of the true class name. Thereafter, a single space may appear, and 





then each succeeding character is used as input by the extension implementation, up until the closing curly brace 
is encountered. 

The .NET XAML implementation uses the MarkupExtension abstract class as the basis for all of the markup 
extensions supported by WPF as well as other frameworks or technologies. The markup extensions that WPF 
specifically implements are often intended to provide a means to reference other existing objects, or to make 
deferred references to objects that will be evaluated at run time. For example, a simple WPF data binding is 
accomplished by specifying the {Binding} markup extension in place of the value that a particular property 
would ordinarily take. Many of the WPF markup extensions enable an attribute syntax for properties where an 
attribute syntax would not otherwise be possible. For example, a Style object is a relatively complex type that 
contains a nested series of objects and properties. Styles in WPF are typically defined as a resource in a 
ResourceDictionary, and then referenced through one of the two WPF markup extensions that request a resource. 
The markup extension defers the evaluation of the property value to a resource lookup and enables providing the 
value of the Style property, taking type Style, in attribute syntax as in the following example: 

<Button Style="{StaticResour'ce MyStyle}">My button</Button> 

Flere, staticResounce identifies the StaticResourceExtension class providing the markup extension 
implementation. The next string Mystyie is used as the input for the non-default StaticResourceExtension 
constructor, where the parameter as taken from the extension string declares the requested ResourceKey. 

Mystyie is expected to be the x:Key value of a Style defined as a resource. The StaticResource Markup Extension 
usage requests that the resource be used to provide the Style property value through static resource lookup logic 
at load time. 

For more information about markup extensions, see Markup Extensions and WPF XAML. For a reference of 
markup extensions and other XAML programming features enabled in the general .NET XAML implementation, 
see XAML Namespace (x:) Language Features. For WPF-specific markup extensions, see WPF XAML Extensions. 

Attached Properties 

Attached properties are a programming concept introduced in XAML whereby properties can be owned and 
defined by a particular type, but set as attributes or property elements on any element. The primary scenario that 
attached properties are intended for is to enable child elements in a markup structure to report information to a 
parent element without requiring an extensively shared object model across all elements. Conversely, attached 
properties can be used by parent elements to report information to child elements. For more information on the 
purpose of attached properties and how to create your own attached properties, see Attached Properties 
Overview. 

Attached properties use a syntax that superficially resembles property element syntax, in that you also specify a 
typeName.propertyNamecombmai\o'n. There are two important differences: 

• You can use the typeName.propertyName coxvMmabon even when setting an attached property through 
attribute syntax. Attached properties are the only case where qualifying the property name is a 
requirement in an attribute syntax. 

• You can also use property element syntax for attached properties. However, for typical property element 
syntax, the typeNameyou specify is the object element that contains the property element. If you are 
referring to an attached property, then the typeName\s the class that defines the attached property, not 
the containing object element. 

Attached Events 

Attached events are another programming concept introduced in XAML where events can be defined by a 
specific type, but handlers may be attached on any object element. In the WOF implementation, often the type 
that defines an attached event is a static type that defines a service, and sometimes those attached events are 







exposed by a routed event alias in types that expose the service. Handlers for attached events are specified 
through attribute syntax. As with attached events, the attribute syntax is expanded for attached events to allow a 
typeA/amaeventA/ame usage, where ^yoeA/ame is the class that provides Add and Remove event handler 
accessors for the attached event infrastructure, and eventName\s the event name. 

Anatomy of a XAML Root Element 

The following table shows a typical XAML root element broken down, showing the specific attributes of a root 
element: 


<Page Opening object element of the root element 

xmlns = "http://schemas.microsoft.com/winfx/ 2006 /xaml/preseTilteid^iatllt (WPF) XAML namespace 

xmlns : x="http: / /schemas. micro soft. com/winf x/ 2006 /xaml" The XAML language XAML namespace 

x:ciass="ExampleNamespace. ExampleCode" The partial class declaration that connects markup to any 

code-behind defined for the partial class 

> End of object element for the root. Object is not closed yet 

because the element contains child elements 


Optional and Nonrecommended XAML Usages 

The following sections describe XAML usages that are technically supported by XAML processors, but that 
produce verbosity or other aesthetic issues that interfere with XAML files remaining human-readable when you 
develop applications that contain XAML sources. 

Optional Property Element Usages 

Optional property element usages include explicitly writing out element content properties that the XAML 
processor considers implicit. For example, when you declare the contents of a Menu, you could choose to 
explicitly declare the Items collection of the Menu as a <Menu. items> property element tag, and place each 
Menultem within <Menu.items> , rather than using the implicit XAML processor behavior that all child elements of 
a Menu must be a Menultem and are placed in the Items collection. Sometimes the optional usages can help to 
visually clarify the object structure as represented in the markup. Or sometimes an explicit property element 
usage can avoid markup that is technically functional but visually confusing, such as nested markup extensions 
within an attribute value. 

Full typeName.memberName Qualified Attributes 

The typeName.memberNameiorm for an attribute actually works more universally than just the routed event 
case. But in other situations that form is superfluous and you should avoid it, if only for reasons of markup style 
and readability. In the following example, each of the three references to the Background attribute are completely 
equivalent: 

<Button Bacl<gnound="Blue"xBackgroundt/Button> 

<Button Button.Background="Blue">Button.Background</Button> 

<Button Control.Backgnound="Blue">Control.Background</Button> 

Button.Background works because the qualified lookup for that property on Button is successful (Background 
was inherited from Control) and Button is the class of the object element or a base class, control.Background 
works because the Control class actually defines Background and Control is a Button base class. 










However, the following typeName.memberName^orm example does not work and is thus shown commented: 


<!--<Button Label.Background="Blue">Does not worl«/Button> --> 

Label is another derived class of Control, and if you had specified Label. Background within a Label object 
element, this usage would have worked. However, because Label is not the class or base class of Button, the 
specified XAML processor behavior is to then process Label.Background as an attached property. 

Label.Background is not an available attached property, and this usage fails. 

baseTypeName.memberName Property Elements 

In an analogous way to how the typeName.memberNameform works for attribute syntax, a 
baseTypeName.memberName syntax works for property element syntax. For instance, the following syntax 
works: 


<Button>Control.Background PE 
<Control.Backgrounds 

cLinearGradlentBrush StartPoint="0,0" EndPoint="l,1"> 

<GradientStop Color="Yellow" Offset="0.0" /> 

<GradientStop Color="LimeGreen" Offset="1.0" /> 

</LinearGradientBrush> 

</Control.Backgrounds 
</Buttons 

Here, the property element was given as control.Background even though the property element was contained 
in Button . 

But just like typeName.memberNameiorm for attributes, baseTypeName.memberName\s poor style in markup, 
and you should avoid it. 

See also 

• XAML Overview (WPF) 

• XAML Namespace (x:) Language Features 

• WPF XAML Extensions 

• Dependency Properties Overview 

• TypeConverters and XAML 

• XAML and Custom Classes for WPF 
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Code-behind is a term used to describe the code that is joined with markup-defined objects, when a XAML page is 
markup-compiled. This topic describes requirements for code-behind as well as an alternative inline code 
mechanism for code in XAML. 

This topic contains the following sections: 

• Prerequisites 

• Code-Behind and the XAML Language 

• Code-behind, Event Handler, and Partial Class Requirements in WPF 

• x:Code 

• Inline Code Limitations 

Prerequisites 

This topic assumes that you have read the XAML Overview (WPF) and have some basic knowledge of the CLR and 
object-oriented programming. 

Code-Behind and the XAML Language 

The XAML language includes language-level features that make it possible to associate code files with markup 
files, from the markup file side. Specifically, the XAML language defines the language features x:Class Directive, 
xiSubclass Directive, and x:ClassModifier Directive. Exactly how the code should be produced, and how to integrate 
markup and code, is not part of what the XAML language specifies. It is left up to frameworks such as WPF to 
determine how to integrate the code, how to use XAML in the application and programming models, and the build 
actions or other support that all this requires. 

Code-behind, Event Handler, and Partial Class Requirements in WPF 

• The partial class must derive from the type that backs the root element. 

• Note that under the default behavior of the markup compile build actions, you can leave the derivation 
blank in the partial class definition on the code-behind side. The compiled result will assume the page root's 
backing type to be the basis for the partial class, even if it not specified. However, relying on this behavior is 
not a best practice. 

• The event handlers you write in the code-behind must be instance methods and cannot be static methods. 
These methods must be defined by the partial class within the CLR namespace identified by x:ciass . You 
cannot qualify the name of an event handler to instruct a XAML processor to look for an event handler for 
event wiring in a different class scope. 

• The handler must match the delegate for the appropriate event in the backing type system. 

• For the Microsoft Visual Basic language specifically, you can use the language-specific Handles keyword to 
associate handlers with instances and events in the handler declaration, instead of attaching handlers with 
attributes in XAML. However, this technique does have some limitations because the Handles keyword 
cannot support all of the specific features of the WPF event system, such as certain routed event scenarios 





or attached events. For details, see Visual Basic and WPF Event Handling. 


x:Code 

x:Code is a directive element defined in XAML. An x:Code directive element can contain inline programming code. 
The code that is defined inline can interact with the XAML on the same page. The following example illustrates 
inline C# code. Notice that the code is inside the xrCode element and that the code must be surrounded by 
<CDATA[ ... ]]> to escape the contents for XML, so that a XAML processor (interpreting either the XAML schema or 
the WPF schema) will not try to interpret the contents literally as XML. 

<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/pnesentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="MyNamespace.MyCanvasCodeInline" 

> 

<Button Name="buttonl" Click="Clicl<ed">Click Me!</Button> 

<x:Code><![CDATA[ 

void Clicked(object sendetj RoutedEventArgs e) 

{ 

buttonl.Content = "Hello World"; 

} 

] ]></x:Code> 

</Page> 


Inline Code Limitations 

You should consider avoiding or limiting the use of inline code. In terms of architecture and coding philosophy, 
maintaining a separation between markup and code-behind keeps the designer and developer roles much more 
distinct. On a more technical level, the code that you write for inline code can be awkward to write, because you 
are always writing into the XAML generated partial class, and can only use the default XML namespace mappings. 
Because you cannot add using statements, you must fully qualify many of the API calls that you make. The default 
WPF mappings include most but not all CLR namespaces that are present in the WPF assemblies; you will have to 
fully qualify calls to types and members contained within the other CLR namespaces. You also cannot define 
anything beyond the partial class in the inline code, and all user code entities you reference must exist as a 
member or variable within the generated partial class. Other language specific programming features, such as 
macros or #ifdef against global variables or build variables, are also not available. For more information, see 
x;Code Intrinsic XAML Type. 

See also 

• XAML Overview (WPF) 

• x:Code Intrinsic XAML Type 

• Building a WPF Application 

• XAML Syntax In Detail 
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XAML as implemented in common language runtime (CLR) frameworks supports the ability to define a custom 
class or structure in any common language runtime (CLR) language, and then access that class using XAML 
markup. You can use a mixture of Windows Presentation Foundation (WPF)-defined types and your custom types 
within the same markup file, typically by mapping the custom types to a XAML namespace prefix. This topic 
discusses the requirements that a custom class must satisfy to be usable as a XAML element. 

Custom Classes in Applications or Assemblies 

Custom classes that are used in XAML can be defined in two distinct ways: within the code-behind or other code 
that produces the primary Windows Presentation Foundation (WPF) application, or as a class in a separate 
assembly, such as an executable or DLL used as a class library. Each of these approaches has particular advantages 
and disadvantages. 

• The advantage of creating a class library is that any such custom classes can be shared across many 
different possible applications. A separate library also makes versioning issues of applications easier to 
control, and simplifies creating a class where the intended class usage is as a root element on a XAML page. 

• The advantage of defining the custom classes in the application is that this technique is relatively 
lightweight and minimizes the deployment and testing issues encountered when you introduce separate 
assemblies beyond the main application executable. 

• Whether defined in the same or different assembly, custom classes need to be mapped between CLR 
namespace and XML namespace in order to be used in XAML as elements. See XAML Namespaces and 
Namespace Mapping for WPF XAML. 

Requirements for a Custom Class as a XAML Element 

In order to be able to be instantiated as an object element, your class must meet the following requirements: 

• Your custom class must be public and support a default (parameterless) public constructor. (See following 
section for notes regarding structures.) 

• Your custom class must not be a nested class. Nested classes and the "dot" in their general CLR usage 
syntax interfere with other WPF and/or XAML features such as attached properties. 

In addition to enabling object element syntax, your object definition also enables property element syntax for any 
other public properties that take that object as the value type. This is because the object can now be instantiated 
as an object element and can fill the property element value of such a property. 

Structures 

Structures that you define as custom types are always able to be constructed in XAML in WPF .This is because the 
CLR compilers implicitly create a parameterless constructor for a structure that initializes all property values to 
their defaults. In some cases, the default construction behavior and/or object element usage for a structure is not 
desirable. This might be because the structure is intended to fill values and function conceptually as a union, 
where the values contained might have mutually exclusive interpretations and thus none of its properties are 
settable. A WPF example of such a structure is GridLength. Generally, such structures should implement a type 
converter such that the values can be expressed in attribute form, using string conventions that create the 
different interpretations or modes of the structure's values. The structure should also expose similar behavior for 
code construction through a non-parameterless constructor. 




Requirements for Properties of a Custom Class as XAML Attributes 

Properties must reference a by-value type (such as a primitive), or use a class for type that has either a 
parameterless constructor or a dedicated type converter that a XAML processor can access. In the CLR XAML 
implementation, XAML processors either find such converters through native support for language primitives, or 
through application of TypeConverterAttribute to a type or member in backing type definitions 

Alternatively, the property may reference an abstract class type, or an interface. For abstract classes or interfaces, 
the expectation for XAML parsing is that the property value must be filled with practical class instances that 
implement the interface, or instances of types that derive from the abstract class. 

Properties can be declared on an abstract class, but can only be set on practical classes that derive from the 
abstract class. This is because creating the object element for the class at all requires a public parameterless 
constructor on the class. 

TypeConverter Enabled Attribute Syntax 

If you provide a dedicated, attributed type converter at the class level, the applied type conversion enables 
attribute syntax for any property that needs to instantiate that type. A type converter does not enable object 
element usage of the type; only the presence of a parameterless constructor for that type enables object element 
usage. Therefore, properties that are type-converter enabled are generally speaking not usable in property syntax, 
unless the type itself also supports object element syntax. The exception to this is that you can specify a property 
element syntax, but have the property element contain a string. That usage is really essentially equivalent to an 
attribute syntax usage, and such a usage is not common unless there is a need for more robust white-space 
handling of the attribute value. For example, the following is a property element usage that takes a string, and the 
attribute usage equivalent; 

<Button>Hallo! 

<Button.Languages 
de-DE 

</Button.Languages 
</Buttons 

<Button Language="de-DE"sHallo!</Buttons 

Examples of properties where attribute syntax is allowed but property element syntax that contains an object 
element is disallowed through XAML are various properties that take the Cursor type. The Cursor class has a 
dedicated type converter CursorConverter, but does not expose a parameterless constructor, so the Cursor 
property can only be set through attribute syntax even though the actual Cursor type is a reference type. 

Per-Property Type Converters 

Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" 
that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as 
input for a ConvertFrom operation based on the appropriate type. Typically this is done to provide a convenience 
accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type 
converters for attributes where you want to use existing CLR types that do not supply either a parameterless 
constructor or an attributed type converter. Examples from the WPF API are certain properties that take the 
Cultureinfo type. In this case, WPF used the existing Microsoft .NET Framework Cultureinfo type to better address 
compatibility and migration scenarios that were used in earlier versions of frameworks, but the Cultureinfo type 
did not support the necessary constructors or type-level type conversion to be usable as a XAML property value 
directly. 

Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should 
strongly consider backing that property with a dependency property. This is particularly true if you use the 
existing Windows Presentation Foundation (WPF) implementation of the XAML processor, because you can 



improve performance by using DependencyProperty backing. A dependency property will expose property 
system features for your property that users will come to expect for a XAML accessible property. This includes 
features such as animation, data binding, and style support. For more information, see Custom Dependency 
Properties and XAML Loading and Dependency Properties. 

Writing and Attributing a Type Converter 

You occasionally will need to write a custom TypeConverter derived class to provide type conversion for your 
property type. For instructions on how to derive from and create a type converter that can support XAML usages, 
and how to apply the TypeConverterAttribute, see TypeConverters and XAML. 

Requirements for XAML Event Handler Attribute Syntax on Events of a 
Custom Class 

To be usable as a CLR event, the event must be exposed as a public event on a class that supports a parameterless 
constructor, or on an abstract class where the event can be accessed on derived classes. In order to be used 
conveniently as a routed event, your CLR event should implement explicit add and remove methods, which add 
and remove handlers for the CLR event signature and forward those handlers to the AddHandler and 
RemoveHandler methods. These methods add or remove the handlers to the routed event handler store on the 
instance that the event is attached to. 


NOTE 

It is possible to register handlers directly for routed events using AddHandler, and to deliberately not define a CLR event 
that exposes the routed event. This is not generally recommended because the event will not enable XAML attribute syntax 
for attaching handlers, and your resulting class will offer a less transparent XAML view of that type's capabilities. 


Writing Collection Properties 

Properties that take a collection type have a XAML syntax that enables you to specify objects that are added to the 

collection. This syntax has two notable features. 

• The object that is the collection object does not need to be specified in object element syntax. The presence 
of that collection type is implicit whenever you specify a property in XAML that takes a collection type. 

• Child elements of the collection property in markup are processed to become members of the collection. 
Ordinarily, the code access to the members of a collection is performed through list/dictionary methods 
such as Add , or through an indexer. But XAML syntax does not support methods or indexers (exception: 

XAML 2009 can support methods, but using XAML 2009 restricts the possible WPF usages; see XAML 2009 
Language Features). Collections are obviously a very common requirement for building a tree of elements, 
and you need some way to populate these collections in declarative XAML. Therefore, child elements of a 
collection property are processed by adding them to the collection that is the collection property type 
value. 

The .NET Framework XAML Services implementation and thus the WPF XAML processor uses the following 

definition for what constitutes a collection property. The property type of the property must implement one of the 

following: 

• Implements IList. 

• Implements IDictionary or the generic equivalent (IDictionary<TKey,TValue>). 

• Derives from Array (for more information about arrays in XAML, see x:Array Markup Extension.) 

• Implements lAddChild (an interface defined by WPF). 






Each of these types in CLR has an Add method, which is used by the XAML processor to add items to the 
underlying collection when creating the object graph. 


NOTE 

The generic List and Dictionary interfaces (IList<T> and IDictionary<TKey,TValue>) are not supported for collection 
detection by the WPF XAML processor. However, you can use the List<T> class as a base class, because it implements IList 
directly, or Dictionary <TKey,TValue> as a base class, because it implements I Dictionary directly. 


When you declare a property that takes a collection, be cautious about how that property value is initialized in 
new instances of the type. If you are not implementing the property as a dependency property, then having the 
property use a backing field that calls the collection type constructor is adequate. If your property is a dependency 
property, then you may need to initialize the collection property as part of the default type constructor. This is 
because a dependency property takes its default value from metadata, and you typically do not want the initial 
value of a collection property to be a static, shared collection. There should be a collection instance per each 
containing type instance. For more information, see Custom Dependency Properties. 

You can implement a custom collection type for your collection property. Because of implicit collection property 
treatment, the custom collection type does not need to provide a parameterless constructor in order to be used in 
XAML implicitly. However, you can optionally provide a parameterless constructor for the collection type. This can 
be a worthwhile practice. Unless you do provide a parameterless constructor, you cannot explicitly declare the 
collection as an object element. Some markup authors might prefer to see the explicit collection as a matter of 
markup style. Also, a parameterless constructor can simplify the initialization requirements when you create new 
objects that use your collection type as a property value. 

Declaring XAML Content Properties 

The XAML language defines the concept of a XAML content property. Each class that is usable in object syntax can 
have exactly one XAML content property. To declare a property to be the XAML content property for your class, 
apply the ContentPropertyAttribute as part of the class definition. Specify the name of the intended XAML content 
property as the Name in the attribute. The property is specified as a string by name, not as a reflection construct 
such as Propertyinfo. 

You can specify a collection property to be the XAML content property. This results in a usage for that property 
whereby the object element can have one or more child elements, without any intervening collection object 
elements or property element tags. These elements are then treated as the value for the XAML content property 
and added to the backing collection instance. 

Some existing XAML content properties use the property type of object . This enables a XAML content property 
that can take primitive values such as a String as well as taking a single reference object value. If you follow this 
model, your type is responsible for type determination as well as the handling of possible types. The typical 
reason for an Object content type is to support both a simple means of adding object content as a string (which 
receives a default presentation treatment), or an advanced means of adding object content that specifies a non¬ 
default presentation or additional data. 

Serializing XAML 

For certain scenarios, such as if you are a control author, you may also want to assure that any object 
representation that can be instantiated in XAML can also be serialized back to equivalent XAML markup. 
Serialization requirements are not described in this topic. See Control Authoring Overview and Element Tree and 
Serialization. 


See also 
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This topic introduces the concept of markup extensions for XAML, including their syntax rules, purpose, and the 
class object model that underlies them. Markup extensions are a general feature of the XAML language and of 
the .NET implementation of XAML services. This topic specifically details markup extensions for use in WPF 
XAML. 

XAML Processors and Markup Extensions 

Generally speaking, a XAML parser can either interpret an attribute value as a literal string that can be 
converted to a primitive, or convert it to an object by some means. One such means is by referencing a type 
converter; this is documented in the topic TypeConverters and XAML. However, there are scenarios where 
different behavior is required. For example, a XAML processor can be instructed that a value of an attribute 
should not result in a new object in the object graph. Instead, the attribute should result in an object graph that 
makes a reference to an already constructed object in another part of the graph, or a static object. Another 
scenario is that a XAML processor can be instructed to use a syntax that provides non-default arguments to the 
constructor of an object. These are the types of scenarios where a markup extension can provide the solution. 

Basic Markup Extension Syntax 

A markup extension can be implemented to provide values for properties in an attribute usage, properties in a 
property element usage, or both. 

When used to provide an attribute value, the syntax that distinguishes a markup extension sequence to a XAML 
processor is the presence of the opening and closing curly braces ({ and }). The type of markup extension is then 
identified by the string token immediately following the opening curly brace. 

When used in property element syntax, a markup extension is visually the same as any other element used to 
provide a property element value: a XAML element declaration that references the markup extension class as an 
element, enclosed within angle brackets (< >). 

XAML-Defined Markup Extensions 

Several markup extensions exist that are not specific to the WPF implementation of XAML, but are instead 
implementations of intrinsics or features of XAML as a language. These markup extensions are implemented in 
the System.XamI assembly as part of the general .NET Framework XAML services, and are within the XAML 
language XAML namespace. In terms of common markup usage, these markup extensions are typically 
identifiable by the x: prefix in the usage. The MarkupExtension base class (also defined in System.XamI) 
provides the pattern that all markup extensions should use in order to be supported in XAML readers and XAML 
writers, including in WPF XAML. 

• x:Type supplies the Type object for the named type. This facility is used most frequently in styles and 
templates. For details, see x:Type Markup Extension. 

• x:static produces static values. The values come from value-type code entities that are not directly the 
type of a target property's value, but can be evaluated to that type. For details, see xiStatic Markup 
Extension. 

• x:Nuii specifies null as a value for a property and can be used either for attributes or property 
element values. For details, see x:Null Markup Extension. 








• xrAnray provides Support for creation of general arrays in XAML syntax, for cases where the collection 
support provided by WPF base elements and control models is deliberately not used. For details, see 
x:Array Markup Extension. 


NOTE 

The x: prefix is used for the typical XAML namespace mapping of the XAML language intrinsics, in the root element of 
a XAML file or production. For example, the Visual Studio templates for WPF applications initiate a XAML file using this 
x: mapping. You could choose a different prefix token in your own XAML namespace mapping, but this documentation 
will assume the default x: mapping as a means of identifying those entities that are a defined part of the XAML 
namespace for the XAML language, as opposed to the WPF default namespace or other XAML namespaces not related 
to a specific framework. 


WPF-Specific Markup Extensions 

The most common markup extensions used in WPF programming are those that support resource references ( 



object graph at run time. For details, see StaticResource Markup Extension. 

• DynamicResource provides a value for a property by deferring that value to be a run-time reference to a 
resource. A dynamic resource reference forces a new lookup each time that such a resource is accessed 
and has access to the object graph at run time. In order to get this access, DynamicResource concept is 
supported by dependency properties in the WPF property system, and evaluated expressions. Therefore 
you can only use DynamicResource for a dependency property target. For details, see DynamicResource 
Markup Extension. 

• Binding provides a data bound value for a property, using the data context that applies to the parent 
object at run time. This markup extension is relatively complex, because it enables a substantial inline 
syntax for specifying a data binding. For details, see Binding Markup Extension. 

• ReiativeSource provides source information for a Binding that can navigate several possible 
relationships in the run-time object tree. This provides specialized sourcing for bindings that are created 
in multi-use templates or created in code without full knowledge of the surrounding object tree. For 
details, see ReiativeSource MarkupExtension. 

• TempiateBinding enables a control template to use values for templated properties that come from 
object-model-defined properties of the class that will use the template. In other words, the property 
within the template definition can access a context that only exists once the template is applied. For 
details, see TempiateBinding Markup Extension. For more information on the practical use of 

TempiateBinding , see Styling with ControlTemplates Sample. 

• coiorConvertedBitmap supports a relatively advanced imaging scenario. For details, see 
ColorConvertedBitmap Markup Extension. 

• ComponentResourceKey and ThemeDictionary support aspects of resource lookup, particularly for 
resources and themes that are packaged with custom controls. For more information, see 
ComponentResourceKey Markup Extension, ThemeDictionary Markup Extension, or Control Authoring 
Overview. 

*Extension Classes 

For both the general XAML language and WPF-specific markup extensions, the behavior of each markup 


















extension is identified to a XAML processor through a *Extension class that derives from MarkupExtension, and 
provides an implementation of the ProvideValue method. This method on each extension provides the object 
that is returned when the markup extension is evaluated. The returned object is typically evaluated based on the 
various string tokens that are passed to the markup extension. 

For example, the StaticResourceExtension class provides the surface implementation of actual resource lookup 
so that its ProvideValue implementation returns the object that is requested, with the input of that particular 
implementation being a string that is used to look up the resource by its x:Key . Much of this implementation 
detail is unimportant if you are using an existing markup extension. 

Some markup extensions do not use string token arguments. This is either because they return a static or 
consistent value, or because context for what value should be returned is available through one of the services 
passed through the serviceProvider parameter. 

The *Extension naming pattern is for convenience and consistency. It is not necessary in order for a XAML 
processor to identify that class as support for a markup extension. So long as your codebase includes 
System.XamI and uses .NET Framework XAML Services implementations, all that is necessary to be recognized 
as a XAML markup extension is to derive from MarkupExtension and to support a construction syntax. WPF 
defines markup extension-enabling classes that do not follow the *Extension naming pattern, for example 
Binding. Typically the reason for this is that the class supports scenarios beyond pure markup extension 
support. In the case of Binding, that class supports run-time access to methods and properties of the object for 
scenarios that have nothing to do with XAML. 

Extension Class Interpretation of Initialization Text 

The string tokens following the markup extension name and still within the braces are interpreted by a XAML 
processor in one of the following ways: 

• A comma always represents the separator or delimiter of individual tokens. 

• If the individual separated tokens do not contain any equals signs, each token is treated as a constructor 
argument. Each constructor parameter must be given as the type expected by that signature, and in the 
proper order expected by that signature. 


NOTE 

A XAML processor must call the constructor that matches the argument count of the number of pairs. For this 
reason, if you are implementing a custom markup extension, do not provide multiple constructors with the same 
argument count. The behavior for how a XAML processor behaves if more than one markup extension 
constructor path with the same parameter count exists is not defined, but you should anticipate that a XAML 
processor is permitted to throw an exception on usage if this situation exists in the markup extension type 
definitions. 


• If the individual separated tokens contain equals signs, then a XAML processor first calls the 
parameterless constructor for the markup extension. Then, each name=value pair is interpreted as a 
property name that exists on the markup extension, and a value to assign to that property. 

• If there is a parallel result between the constructor behavior and the property setting behavior in a 
markup extension, it does not matter which behavior you use. It is more common usage to use the 
property = value pairs for markup extensions that have more than one settable property, if only because 
it makes your markup more intentional and you are less likely to accidentally transpose constructor 
parameters. (When you specify property=value pairs, those properties may be in any order.) Also, there 
is no guarantee that a markup extension supplies a constructor parameter that sets every one of its 
settable properties. For example. Binding is a markup extension, with many properties that are settable 
through the extension in property = va/c/eform, but Binding only supports two constructors: a 
parameterless constructor, and one that sets an initial path. 








• A literal comma cannot be passed to a markup extension without escapement 


Escape Sequences and Markup Extensions 

Attribute handling in a XAML processor uses the curly braces as indicators of a markup extension sequence. It is 
also possible to produce a literal curly brace character attribute value if necessary, by entering an escape 
sequence using an empty curly brace pair followed by the literal curly brace. See {} Escape Sequence - Markup 
Extension. 

Nesting Markup Extensions in XAML Usage 


Nesting of multiple markup extensions is supported, and each markup extension will be evaluated deepest first. 
For example, consider the following usage: 



Markup Extensions and Property Element Syntax 

When used as an object element that fills a property element value, a markup extension class is visually 
indistinguishable from a typical type-backed object element that can be used in XAML. The practical difference 
between a typical object element and a markup extension is that the markup extension is either evaluated to a 
typed value or deferred as an expression. Therefore the mechanisms for any possible type errors of property 
values for the markup extension will be different, similar to how a late-bound property is treated in other 
programming models. An ordinary object element will be evaluated for type match against the target property 
it is setting when the XAML is parsed. 

Most markup extensions, when used in object element syntax to fill a property element, would not have content 
or any further property element syntax within. Thus you would close the object element tag, and provide no 
child elements. Whenever any object element is encountered by a XAML processor, the constructor for that class 
is called, which instantiates the object created from the parsed element. A markup extension class is no 
different: if you want your markup extension to be usable in object element syntax, you must provide a 
parameterless constructor. Some existing markup extensions have at least one required property value that 
must be specified for effective initialization. If so, that property value is typically given as a property attribute on 
the object element. In the XAML Namespace (x:) Language Features and WPF XAML Extensions reference pages, 
markup extensions that have required properties (and the names of required properties) will be noted. 
Reference pages will also note if either object element syntax or attribute syntax is disallowed for particular 
markup extensions. A notable case is x:Array Markup Extension, which cannot support attribute syntax because 
the contents of that array must be specified within the tagging as content. The array contents are handled as 
general objects, therefore no default type converter for the attribute is feasible. Also, x:Array Markup Extension 
requires a type parameter. 

See also 

• XAML Overview (WPF) 

• XAML Namespace (x:) Language Features 

• WPF XAML Extensions 

• StaticResource Markup Extension 

• Binding Markup Extension 
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This topic further explains the presence and purpose of the two XAML namespace mappings as often found in the 
root tag of a WPF XAML file. It also describes how to produce similar mappings for using elements that are 
defined in your own code, and/or within separate assemblies. 

What is a XAML Namespace? 

A XAML namespace is really an extension of the concept of an XML namespace. The techniques of specifying a 
XAML namespace rely on the XML namespace syntax, the convention of using URIs as namespace identifiers, 
using prefixes to provide a means to reference multiple namespaces from the same markup source, and so on. 
The primary concept that is added to the XAML definition of the XML namespace is that a XAML namespace 
implies both a scope of uniqueness for the markup usages, and also influences how markup entities are 
potentially backed by specific CLR namespaces and referenced assemblies. This latter consideration is also 
influenced by the concept of a XAML schema context. But for purposes of how WPF works with XAML 
namespaces, you can generally think of XAML namespaces in terms of a default XAML namespace, the XAML 
language namespace, and any further XAML namespaces as mapped by your XAML markup directly to specific 
backing CLR namespaces and referenced assemblies. 

The WPF and XAML Namespace Declarations 

Within the namespace declarations in the root tag of many XAML files, you will see that there are typically two 
XML namespace declarations. The first declaration maps the overall WPF client / framework XAML namespace as 
the default: 


xmlns="http://schemas.microsoft.com/winfx/ 2006 /xaml/presentation" 

The second declaration maps a separate XAML namespace, mapping it (typically) to the x: prefix, 
xmlns:x="http://schemas.microsoft.com/winfx/ 2006 /xaml" 

The relationship between these declarations is that the x: prefix mapping supports the intrinsics that are part of 
the XAML language definition, and WPF is one implementation that uses XAML as a language and defines a 
vocabulary of its objects for XAML. Because the WPF vocabulary's usages will be far more common than the 
XAML intrinsics usages, the WPF vocabulary is mapped as the default. 

The x: prefix convention for mapping the XAML language intrinsics support is followed by project templates, 
sample code, and the documentation of language features within this SDK. The XAML namespace defines many 
commonly-used features that are necessary even for basic WPF applications. For instance, in order to join any 
code-behind to a XAML file through a partial class, you must name that class as the xrciass attribute in the root 
element of the relevant XAML file. Or, any element as defined in a XAML page that you wish to access as a keyed 
resource should have the x:Key attribute set on the element in question. For more information on these and 
other aspects of XAML see XAML Overview (WPF) or XAML Syntax In Detail. 

Mapping to Custom Classes and Assemblies 

You can map XML namespaces to assemblies using a series of tokens within an xmlns prefix declaration, similar 
to how the standard WPF and XAML-intrinsics XAML namespaces are mapped to prefixes. 











The syntax takes the following possible named tokens and following values: 

cir-namespace: The CLR namespace declared within the assembly that contains the public types to expose as 
elements. 

assembiy= The assembly that contains some or all of the referenced CLR namespace. This value is typically just 
the name of the assembly, not the path, and does not include the extension (such as .dll or .exe). The path to that 
assembly must be established as a project reference in the project file that contains the XAML you are trying to 
map. In order to incorporate versioning and strong-name signing, the assembly value can be a string as defined 
by AssemblyName, rather than the simple string name. 

Note that the character separating the cir-namespace token from its value is a colon (:) whereas the character 
separating the assembly token from its value is an equals sign (=). The character to use between these two tokens 
is a semicolon. Also, do not include any white space anywhere in the declaration. 

A Basic Custom Mapping Example 

The following code defines an example custom class: 

namespace SDKSample { 

public class ExampleClass : ContentControl { 
public ExampleClass() { 

} 

} 

} 

Namespace SDKSample 

Public Class ExampleClass 
Inherits ContentControl 

Public Sub New() 

End Sub 
End Class 
End Namespace 

This custom class is then compiled into a library, which per the project settings (not shown) is named 
SDKSamplelibrary . 

In order to reference this custom class, you also need to include it as a reference for your current project, which 
you would typically do using the Solution Explorer Ul in Visual Studio. 

Now that you have a library containing a class, and a reference to it in project settings, you can add the following 
prefix mapping as part of your root element in XAML: 

xmlns:custom="cir-namespace:SDKSample;assembly=SDKSampleLibrary" 


To put it all together, the following is XAML that includes the custom mapping along with the typical default and x: 
mappings in the root tag, then uses a prefixed reference to instantiate ExampleClass in that Ul: 

<Page x:Class="WPFApplicationl.MainPage" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

xmlns:custom="cir-namespace:SDKSample;assembly=SDKSampleLibrary"> 

ccustom:ExampleClass/> 

</Page> 












Mapping to Current Assemblies 

assembly can be omitted if the cir-namespace referenced is being defined within the Same assembly as the 
application code that is referencing the custom classes. Or, an equivalent syntax for this case is to specify 
assembiy= , with no String token following the equals sign. 

Custom classes cannot be used as the root element of a page if defined in the same assembly. Partial classes do 
not need to be mapped; only classes that are not the partial class of a page in your application need to be mapped 
if you intend to reference them as elements in XAML. 

Mapping CLR Namespaces to XML Namespaces in an Assembly 

WPF defines a CLR attribute that is consumed by XAML processors in order to map multiple CLR namespaces to a 
single XAML namespace. This attribute, XmlnsDefinitionAttribute, is placed at the assembly level in the source 
code that produces the assembly. The WPF assembly source code uses this attribute to map the various common 
namespaces, such as System.Windows and System.Windows.Controls, to the 
http: //schemas.microsoft.com/winfx/2006/xaml/presentation namespace. 

The XmlnsDefinitionAttribute takes two parameters: the XML/XAML namespace name, and the CLR namespace 
name. More than one XmlnsDefinitionAttribute can exist to map multiple CLR namespaces to the same XML 
namespace. Once mapped, members of those namespaces can also be referenced without full qualification if 
desired by providing the appropriate using statement in the partial-class code-behind page. For more details, see 
XmlnsDefinitionAttribute. 

Designer Namespaces and Other Prefixes From XAML Templates 

If you are working with development environments and/or design tools for WPF XAML, you may notice that there 
are other defined XAML namespaces / prefixes within the XAML markup. 

WPF Designer for Visual Studio uses a designer namespace that is typically mapped to the prefix d: . More recent 
project templates for WPF might pre-map this XAML namespace to support interchange of the XAML between 
WPF Designer for Visual Studio and other design environments. This design XAML namespace is used to 
perpetuate design state while roundtripping XAML-based Ul in the designer. It is also used for features such as 
drisDataSounce , which enable runtime data sources in a designer. 

Another prefix you might see mapped is me:, me: is for markup compatibility, and is leveraging a markup 
compatibility pattern that is not necessarily XAML-specific. To some extent, the markup compatibility features can 
be used to exchange XAML between frameworks or across other boundaries of backing implementation, work 
between XAML schema contexts, provide compatibility for limited modes in designers, and so on. For more 
information on markup compatibility concepts and how they relate to WPF, see Markup Compatibility (me:) 
Language Features. 

WPF and Assembly Loading 

The XAML schema context for WPF integrates with the WPF application model, which in turn uses the CLR-defined 
concept of AppDomain. The following sequence describes how XAML schema context interprets how to either 
load assemblies or find types at run time or design time, based on the WPF use of AppDomain and other factors. 

1. Iterate through the AppDomain, looking for an already-loaded assembly that matches all aspects of the 
name, starting from the most recently loaded assembly. 

2. If the name is qualified, call Assembly.Load(String) on the qualified name. 

3. If the short name + public key token of a qualified name matches the assembly that the markup was 
loaded from, return that assembly. 

4. Use the short name + public key token to call Assembly.Load(String). 










5. If the name is unqualified, call Assembly.LoadWithPartialName. 

Loose XAML does not use Step 3; there is no loaded-from assembly. 

Compiled XAML for WPF (generated via XamIBuildTask) does not use the already-loaded assemblies from 
AppDomain (Step 1). Also, the name should never be unqualified from XamIBuildTask output, so Step 5 does not 
apply. 

Compiled BAML (generated via PresentationBuildTask) uses all steps, although BAML also should not contain 
unqualified assembly names. 

See also 

• Understanding XML Namespaces 

• XAML Overview (WPF) 
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XAML namescopes are a concept that identifies objects that are defined in XAML. The names in a XAML namescope 
can be used to establish relationships between the XAML-defined names of objects and their instance equivalents 
in an object tree. Typically, XAML namescopes in WPF managed code are created when loading the individual 
XAML page roots for a XAML application. XAML namescopes as the programming object are defined by the 
INameScope interface and are also implemented by the practical class NameScope. 

Namescopes in Loaded XAML Applications 

In a broader programming or computer science context, programming concepts often include the principle of a 
unique identifier or name that can be used to access an object. For systems that use identifiers or names, the 
namescope defines the boundaries within which a process or technique will search if an object of that name is 
requested, or the boundaries wherein uniqueness of identifying names is enforced. These general principles are 
true for XAML namescopes. In WPF, XAML namescopes are created on the root element for a XAML page when the 
page is loaded. Each name specified within the XAML page starting at the page root is added to a pertinent XAML 
namescope. 

In WPF XAML, elements that are common root elements (such as Page, and Window) always control a XAML 
namescope. If an element such as FrameworkElement or FrameworkContentElement is the root element of the 
page in markup, a XAML processor adds a Page root implicitly so that the Page can provide a working XAML 
namescope. 


NOTE 

WPF build actions create a XAML namescope for a XAML production even if no Name or x:Name attributes are defined on 
any elements in the XAML markup. 


If you try to use the same name twice in any XAML namescope, an exception is raised. For WPF XAML that has 
code-behind and is part of a compiled application, the exception is raised at build time by WPF build actions, when 
creating the generated class for the page during the initial markup compile. For XAML that is not markup-compiled 
by any build action, exceptions related to XAML namescope issues might be raised when the XAML is loaded. 

XAML designers might also anticipate XAML namescope issues at design time. 

Adding Objects to Runtime Object Trees 

The moment that XAML is parsed represents the moment in time that a WPF XAML namescope is created and 
defined. If you add an object to an object tree at a point in time after the XAML that produced that tree was parsed, 
a Name or x:Name value on the new object does not automatically update the information in a XAML namescope. 
To add a name for an object into a WPF XAML namescope after XAML is loaded, you must call the appropriate 
implementation of RegisterName on the object that defines the XAML namescope, which is typically the XAML 
page root. If the name is not registered, the added object cannot be referenced by name through methods such as 
FindName, and you cannot use that name for animation targeting. 

The most common scenario for application developers is that you will use RegisterName to register names into the 
XAML namescope on the current root of the page. RegisterName is part of an important scenario for storyboards 
that target objects for animations. For more information, see Storyboards Overview. 

If you call RegisterName on an object other than the object that defines the XAML namescope, the name is still 
registered to the XAML namescope that the calling object is held within, as if you had called RegisterName on the 







XAML namescope defining object. 


XAML Namescopes in Code 

You can create and then use XAML namescopes in code. The APIs and the concepts involved in XAML namescope 
creation are the same even for a pure code usage, because the XAML processor for WPF uses these APIs and 
concepts when it processes XAML itself The concepts and API exist mainly for the purpose of being able to find 
objects by name within an object tree that is typically defined partially or entirely in XAML. 

For applications that are created programmatically, and not from loaded XAML, the object that defines a XAML 
namescope must implement INameScope, or be a FrameworkElement or FrameworkContentElement derived class, 
in order to support creation of a XAML namescope on its instances. 

Also, for any element that is not loaded and processed by a XAML processor, the XAML namescope for the object is 
not created or initialized by default. You must explicitly create a new XAML namescope for any object that you 
intend to register names into subsequently. To create a XAML namescope, you call the static SetNameScope 
method. Specify the object that will own it as the dependencyobject parameter, and a new NameScope constructor 
call as the value parameter. 

If the object provided as dependencyobject for SetNameScope is not a INameScope implementation, 
FrameworkElement or FrameworkContentElement, calling RegisterName on any child elements will have no effect. 
If you fail to create the new XAML namescope explicitly, then calls to RegisterName will raise an exception. 

For an example of using XAML namescope APIs in code, see Define a Name Scope. 

XAML Namescopes in Styles and Templates 

Styles and templates in WPF provide the ability to reuse and reapply content in a straightforward way. However, 
styles and templates might also include elements with XAML names defined at the template level. That same 
template might be used multiple times in a page. For this reason, styles and templates both define their own XAML 
namescopes, independent of whatever location in an object tree where the style or template is applied. 

Consider the following example: 

<Page 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

> 

<Page.Resounces> 

<ContnolTemplate x:Key="MyButtonTemplate" TargetType="{x:Type Button}"> 

<Bonder BorderBnush="Red" Name="TheBorden" BorderThickness="2"> 

<ContentPnesenter/> 

</Borden> 

</ControlTemplate> 

</Page.Resources> 

<StackPanel> 

<Button Template="{StaticResource MyButtonTemplate}">My first button</Button> 

<Button Template="{StaticResource MyButtonTemplate}">My second button</Button> 

</StackPanel> 

</Page> 


Here, the same template is applied to two different buttons. If templates did not have discrete XAML namescopes, 
the TheBonder name used in the template would cause a name collision in the XAML namescope. Each 
instantiation of the template has its own XAML namescope, so in this example each instantiated template's XAML 
namescope would contain exactly one name. 

Styles also define their own XAML namescope, mostly so that parts of storyboards can have particular names 
assigned. These names enable control specific behaviors that will target elements of that name, even if the 
template was re-defined as part of control customization. 







Because of the separate XAML namescopes, finding named elements in a template is more challenging than 
finding a non-templated named element in a page. You first need to determine the applied template, by getting the 
Template property value of the control where the template is applied. Then, you call the template version of 
FindName, passing the control where the template was applied as the second parameter. 

If you are a control author and you are generating a convention where a particular named element in an applied 
template is the target for a behavior that is defined by the control itself, you can use the GetTemplateChild method 
from your control implementation code. The GetTemplateChild method is protected, so only the control author has 
access to it. 

If you are working from within a template, and need to get to the XAML namescope where the template is applied, 
get the value of TemplatedParent, and then call FindName there. An example of working within the template would 
be if you are writing the event handler implementation where the event will be raised from an element in an 
applied template. 

XAML Namescopes and Name-related APIs 

FrameworkElement has FindName, RegisterName and UnregisterName methods. If the object you call these 
methods on owns a XAML namescope, the methods call into the methods of the relevant XAML namescope. 
Otherwise, the parent element is checked to see if it owns a XAML namescope, and this process continues 
recursively until a XAML namescope is found (because of the XAML processor behavior, there is guaranteed to be a 
XAML namescope at the root). FrameworkContentElement has analogous behaviors, with the exception that no 
FrameworkContentElement will ever own a XAML namescope. The methods exist on FrameworkContentElement 
so that the calls can be forwarded eventually to a FrameworkElement parent element. 

SetNameScope is used to map a new XAML namescope to an existing object. You can call SetNameScope more 
than once in order to reset or clear the XAML namescope, but that is not a common usage. Also, GetNameScope is 
not typically used from code. 

XAML Namescope Implementations 

The following classes implement INameScope directly: 

• NameScope 

• Style 

• ResourceDictionary 

• FrameworkTemplate 

ResourceDictionary does not use XAML names or namescopes ; it uses keys instead, because it is a dictionary 
implementation. The only reason that ResourceDictionary implements INameScope is so it can raise exceptions to 
user code that help clarify the distinction between a true XAML namescope and how a ResourceDictionary handles 
keys, and also to assure that XAML namescopes are not applied to a ResourceDictionary by parent elements. 

FrameworkTemplate and Style implement INameScope through explicit interface definitions. The explicit 
implementations allow these XAML namescopes to behave conventionally when they are accessed through the 
INameScope interface, which is how XAML namescopes are communicated by WPF internal processes. But the 
explicit interface definitions are not part of the conventional API surface of FrameworkTemplate and Style, because 
you seldom need to call the INameScope methods on FrameworkTemplate and Style directly, and instead would 
use other API such as GetTemplateChild. 

The following classes define their own XAML namescope, by using the System.Windows.NameScope helper class 
and connecting to its XAML namescope implementation through the NameScope.NameScope attached property: 

• FrameworkElement 


• FrameworkContentElement 


See also 

• XAML Namespaces and Namespace Mapping for WPF XAML 

• x:Name Directive 
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Windows Presentation Foundation (WPF) provides Style objects and template objects (FrameworkTemplate 
subclasses) as a way to define the visual appearance of an element in resources, so that they can be used multiple 
times. For this reason, attributes in XAML that take the types Style and FrameworkTemplate almost always make 
resource references to existing styles and templates rather than define new ones inline. 

Limitations of Inline Styles and Templates 

In Extensible Application Markup Language (XAML), style and template properties can technically be set in one of 
two ways. You can use attribute syntax to reference a style that was defined within a resource, for example < object 
styie="{staticResour'ce myResourceKey }" .../>. Or you can use property element syntax to define a style inline, 
for instance: 

< object > 

< object .Style> 

< style .../> 

</ object .Style> 

</ object > 

The attribute usage is much more common. A style that is defined inline and not defined in resources is necessarily 
scoped to the containing element only, and cannot be re-used as easily because it has no resource key. In general a 
resource-defined style is more versatile and useful, and is more in keeping with the general Windows Presentation 
Foundation (WPF) programming model principle of separating program logic in code from design in markup. 

Usually there is no reason to set a style or template inline, even if you only intend to use that style or template in 
that location. Most elements that can take a style or template also support a content property and a content model. 
If you are only using whatever logical tree you create through styling or templating once, it would be even easier to 
Just fill that content property with the equivalent child elements in direct markup. This would bypass the style and 
template mechanisms altogether. 

Other syntaxes enabled by markup extensions that return an object are also possible for styles and templates. Two 
such extensions that have possible scenarios include TemplateBinding and Binding. 

See also 


Styling and Templating 
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This topic introduces the purpose of type conversion from string as a general XAML language feature. In the .NET 
Framework, the TypeConverter class serves a particular purpose as part of the implementation for a managed 
custom class that can be used as a property value in XAML attribute usage. If you write a custom class, and you 
want instances of your class to be usable as XAML settable attribute values, you might need to apply a 
TypeConverterAttribute to your class, write a custom TypeConverter class, or both. 

Type Conversion Concepts 

XAML and String Values 

When you set an attribute value in a XAML file, the initial type of that value is a string in pure text. Even other 
primitives such as Double are initially text strings to a XAML processor. 

A XAML processor needs two pieces of information in order to process an attribute value. The first piece of 
information is the value type of the property that is being set. Any string that defines an attribute value and that is 
processed in XAML must ultimately be converted or resolved to a value of that type. If the value is a primitive that 
is understood by the XAML parser (such as a numeric value), a direct conversion of the string is attempted. If the 
value is an enumeration, the string is used to check for a name match to a named constant in that enumeration. If 
the value is neither a parser-understood primitive nor an enumeration, then the type in question must be able to 
provide an instance of the type, or a value, based on a converted string. This is done by indicating a type converter 
class. The type converter is effectively a helper class for providing values of another class, both for the XAML 
scenario and also potentially for code calls in .NET code. 

Using Existing Type Conversion Behavior in XAML 

Depending on your familiarity with the underlying XAML concepts, you may already be using type conversion 
behavior in basic application XAML without realizing it. For instance, WPF defines literally hundreds of properties 
that take a value of type Point. A Point is a value that describes a coordinate in a two-dimensional coordinate 
space, and it really just has two important properties: X and Y. When you specify a point in XAML, you specify it as 
a string with a delimiter (typically a comma) between the X and Y values you provide. For example: 
<LinearGradientBrush StartPoint="0,0" EndPoint="l,l"/> . 

Even this simple type of Point and its simple usage in XAML involve a type converter. In this case that is the class 
PointConverter. 

The type converter for Point defined at the class level streamlines the markup usages of all properties that take 
Point. Without a type converter here, you would need the following much more verbose markup for the same 
example shown previously: 

<LinearGradientBrush> 

<LinearGradlentBrush.StartPoint> 

<Point X="0" Y="0"/> 

</LinearGradientBrush.StartPoint) 

<LinearGradientBrush.EndPoint) 

<Point X="l" Y="l"/> 

</LinearGradientBrush.EndPoint) 

</LinearGradientBrush) 

Whether to use the type conversion string or a more verbose equivalent syntax is generally a coding style choice. 
Your XAML tooling workflow might also influence how values are set. Some XAML tools tend to emit the most 






verbose form of the markup because it is easier to round-trip to designer views or its own serialization 
mechanism. 

Existing type converters can generally be discovered on WPF and .NET Framework types by checking a class (or 
property) for the presence of an applied TypeConverterAttribute. This attribute will name the class that is the 
supporting type converter for values of that type, for XAML purposes as well as potentially other purposes. 

Type Converters and Markup Extensions 

Markup extensions and type converters fill orthogonal roles in terms of XAML processor behavior and the 
scenarios that they are applied to. Although context is available for markup extension usages, type conversion 
behavior of properties where a markup extension provides a value is generally is not checked in the markup 
extension implementations. In other words, even if a markup extension returns a text string as its ProvideVaiue 
output, type conversion behavior on that string as applied to a specific property or property value type is not 
invoked. Generally, the purpose of a markup extension is to process a string and return an object without any type 
converter involved. 

One common situation where a markup extension is necessary rather than a type converter is to make a reference 
to an object that already exists. At best, a stateless type converter could only generate a new instance, which might 
not be desirable. For more information on markup extensions, see Markup Extensions and WPF XAML. 

Native Type Converters 

In the WPF and .NET Framework implementation of the XAML parser, there are certain types that have native type 
conversion handling, yet are not types that might conventionally be thought of as primitives. An example of such a 
type is DateTime. The reason for this is based on how the .NET Framework architecture works: the type DateTime 
is defined in mscorlib, the most basic library in .NET. DateTime is not permitted to be attributed with an attribute 
that comes from another assembly that introduces a dependency (TypeConverterAttribute is from System) so the 
usual type converter discovery mechanism by attributing cannot be supported. Instead, the XAML parser has a list 
of types that need such native processing and processes these similarly to how the true primitives are processed. 
(In the case of DateTime this involves a call to Parse.) 

Implementing a Type Converter 

TypeConverter 

In the Point example given previously, the class PointConverter was mentioned. For .NET implementations of 
XAML, all type converters that are used for XAML purposes are classes that derive from the base class 
TypeConverter. The TypeConverter class existed in versions of .NET Framework that precede the existence of 
XAML; one of its original usages was to provide string conversion for property dialogs in visual designers. For 
XAML, the role of TypeConverter is expanded to include being the base class for to-string and from-string 
conversions that enable parsing a string attribute value, and possibly processing a run-time value of a particular 
object property back into a string for serialization as an attribute. 

TypeConverter defines four members that are relevant for converting to and from strings for XAML processing 
purposes: 

• CanConvertTo 

• CanConvertFrom 

• ConvertTo 

• ConvertFrom 

Of these, the most important method is ConvertFrom. This method converts the input string to the required 
object type. Strictly speaking, the ConvertFrom method could be implemented to convert a much wider range of 
types into the converter's intended destination type, and thus serve purposes that extend beyond XAML such as 
supporting run-time conversions, but for XAML purposes it is only the code path that can process a String input 



that matters. 


The next most important method is ConvertTo. If an application is converted to a markup representation (for 
instance, if it is saved to XAML as a file), ConvertTo is responsible for producing a markup representation. In this 
case, the code path that matters for XAML is when you pass a destinationtype of String . 

CanConvertTo and CanConvertFrom are support methods that are used when a service queries the capabilities of 
the TypeConverter implementation. You must implement these methods to return true for type-specific cases 
that the equivalent conversion methods of your converter support. For XAML purposes, this generally means the 
String type. 

Culture Information and Type Converters for XAML 

Each TypeConverter implementation can have its own interpretation of what constitutes a valid string for a 
conversion, and can also use or ignore the type description passed as parameters. There is an important 
consideration with regard to culture and XAML type conversion. Using localizable strings as attribute values is 
entirely supported by XAML. But using that localizable string as type converter input with specific culture 
requirements is not supported, because type converters for XAML attribute values involve a necessarily fixed- 
language parsing behavior, using en-us culture. For more information on the design reasons for this restriction, 
you should consult the XAML language specification ([MS-XAML]. 

As an example where culture can be an issue, some cultures use a comma as their decimal point delimiter for 
numbers. This will collide with the behavior that many of the WPF XAML type converters have, which is to use a 
comma as a delimiter (based on historical precedents such as the common X,Y form, or comma delimited lists). 
Even passing a culture in the surrounding XAML (setting Language or xmiriang to the si-si culture, an example 
of a culture that uses a comma for decimal in this way) does not solve the issue. 

Implementing ConvertFrom 

To be usable as a TypeConverter implementation that supports XAML, the ConvertFrom method for that converter 
must accept a string as the value parameter. If the string was in valid format, and can be converted by the 
TypeConverter implementation, then the returned object must support a cast to the type expected by the property. 
Otherwise, the ConvertFrom implementation must return null . 

Each TypeConverter implementation can have its own interpretation of what constitutes a valid string for a 
conversion, and can also use or ignore the type description or culture contexts passed as parameters. However, the 
WPF XAML processing might not pass values to the type description context in all cases, and also might not pass 
culture based on xmiiiang . 


NOTE 

Do not use the curly brace characters, particularly {, as a possible element of your string format. These characters are 
reserved as the entry and exit for a markup extension sequence. 


Implementing ConvertTo 

ConvertTo is potentially used for serialization support. Serialization support through ConvertTo for your custom 
type and its type converter is not an absolute requirement. However, if you are implementing a control, or using 
serialization of as part of the features or design of your class, you should implement ConvertTo. 

To be usable as a TypeConverter implementation that supports XAML, the ConvertTo method for that converter 
must accept an instance of the type (or a value) being supported as the value parameter. When the 
destinationtype parameter is the type String, then the returned object must be able to be cast as String. The 
returned string must represent a serialized value of value . Ideally, the serialization format you choose should be 
capable of generating the same value if that string were passed to the ConvertFrom implementation of the same 
converter, without significant loss of information. 














If the value cannot be serialized, or the converter does not support serialization, the ConvertTo implementation 
must return null , and is permitted to throw an exception in this case. But if you do throw exceptions, you should 
report the inability to use that conversion as part of your CanConvertTo implementation so that the best practice 
of checking with CanConvertTo first to avoid exceptions is supported. 

If destinationType parameter is not of type String, you can choose your own converter handling. Typically, you 
would revert to base implementation handling, which in the basemost ConvertTo raises a specific exception. 

Implementing CanConvertTo 

Your CanConvertTo implementation should return true for destinationType of type String, and otherwise defer 
to the base implementation. 

Implementing CanConvertFrom 

Your CanConvertFrom implementation should return true for sourceType of type String, and otherwise defer to 
the base implementation. 

Applying the TypeConverterAttribute 

In order for your custom type converter to be used as the acting type converter for a custom class by a XAML 
processor, you must apply the TypeConverterAttribute to your class definition. The ConverterTypeName that you 
specify through the attribute must be the type name of your custom type converter. With this attribute applied, 
when a XAML processor handles values where the property type uses your custom class type, it can input strings 
and return object instances. 

You can also provide a type converter on a per-property basis. Instead of applying a TypeConverterAttribute to the 
class definition, apply it to a property definition (the main definition, not the get / set implementations within it). 
The type of the property must match the type that is processed by your custom type converter. With this attribute 
applied, when a XAML processor handles values of that property, it can process input strings and return object 
instances. The per-property type converter technique is particularly useful if you choose to use a property type 
from Microsoft .NET Framework or from some other library where you cannot control the class definition and 
cannot apply a TypeConverterAttribute there. 

See also 

• TypeConverter 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• XAML Syntax In Detail 
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Defers a property value to be a data-bound value, creating an intermediate expression object and interpreting the 
data context that applies to the element and its binding at run time. 

Binding Expression Usage 

<object property="{Binding}" .../> 

-on- 

<object property="{Binding bindPropl=valuel[j bindPropN=valueN]*}" ... 

/> 

-or- 

<object property="{Binding path}" .../> 

-on 

<object property="{Binding path[j bindPropN=valueN]*}" .../> 


Syntax Notes 

In these syntaxes, the [] and * are not literals. They are part of a notation to indicate that zero or more 
bindProp ^ ra/c/e pairs can be used, with a , separator between them and preceding id/'/rc/PTOp = value pans. 

Any of the properties listed in the "Binding Properties That Can Be Set with the Binding Extension" section could 
instead be set using attributes of a Binding object element. However, that is not truly the markup extension usage 
of Binding, it is just the general XAML processing of attributes that set properties of the CLR Binding class. In other 
words, <Binding bindPropI =" value! "[ bIndPropN =" valueN '"[*/> is an equivalent syntax for attributes of 
Binding object element usage instead of a Binding expression usage. To learn about the XAML attribute usage of 
specific properties of Binding, see the "XAML Attribute Usage" section of the relevant property of Binding in the 
.NET Framework Class Library. 

XAML Values 


bindPropi, bindPnopN The name of the Binding or BindingBase property to set. Not 

all Binding properties can be set with the Binding 
extension, and some properties are settable within a 

extensions. See "Binding Properties That Can Be Set with the 
Binding Extension" section. 


Binding expression only by using further nested markup 


valueij valueN The value to set the property to. The handling of the 

attribute value is ultimately specific to the type and logic of 
the specific Binding property being set. 


path 


The path string that sets the implicit Binding.Path property. 
See also PropertyPath XAML Syntax. 


Unqualified {Binding} 


The {Binding} usage shown in "Binding Expression Usage" creates a Binding object with default values, which 














includes an initial Binding.Path of null . This is still useful in many scenarios, because the created Binding might 
be relying on key data binding properties such as Binding.Path and Binding.Source being set in the run-time data 
context. For more information on the concept of data context, see Data Binding. 

Implicit Path 

The Binding markup extension uses Binding.Path as a conceptual "default property", where Path= does not need 
to appear in the expression. If you specify a Binding expression with an implicit path, the implicit path must 
appear first in the expression, prior to any other bindProp = value pairs where the Binding property is specified 
by name. For example: {Binding Pathstning} , where Pathstning is a string that is evaluated to be the value of 
Binding.Path in the Binding created by the markup extension usage. You can append an implicit path with other 
named properties after the comma separator, for example, {Binding lastName, Mode=Twoway} . 

Binding Properties That Can Be Set with the Binding Extension 

The syntax shown in this topic uses the generic bindProp = value approximation, because there are many 
read/write properties of BindingBase or Binding that can be set through the Binding markup extension / 
expression syntax. They can be set in any order, with the exception of an implicit Binding.Path. (You do have the 
option to explicitly specify Path= , in which case it can be set in any order). Basically, you can set zero or more of 
the properties in the list below, using bindProp = value pairs separated by commas. 

Several of these property values require object types that do not support a native type conversion from a text 
syntax in XAML, and thus require markup extensions in order to be set as an attribute value. Check the XAML 
Attribute Usage section in the .NET Framework Class Library for each property for more information; the string 
you use for XAML attribute syntax with or without further markup extension usage is basically the same as the 
value you specify in a Binding expression, with the exception that you do not place quotation marks around each 
bindProp = value in the Binding expression. 

• BindingGroupName: a string that identifies a possible binding group. This is a relatively advanced binding 
concept; see reference page for BindingGroupName. 

• BindsDirectlyToSource: Boolean, can be either true or false . The default is false . 

• Converter: can be set as a bindProp = value string in the expression, but to do so requires an object 
reference for the value, such as a StaticResource Markup Extension. The value in this case is an instance of a 
custom converter class. 

• ConverterCulture: settable in the expression as a standards-based identifier; see the reference topic for 
ConverterCulture. 

• ConverterParameter: can be set as a bindProp = value string in the expression, but this is dependent on 
the type of the parameter being passed. If passing a reference type for the value, this usage requires an 
object reference such as a nested StaticResource Markup Extension. 

• ElementName: mutually exclusive versus RelativeSource and Source; each of these binding properties 
represents a particular binding methodology. See Data Binding Overview. 

• FallbackValue; can be set as a bindProp = value string in the expression, but this is dependent on the type 
of the value being passed. If passing a reference type, requires an object reference such as a nested 
StaticResource Markup Extension. 

• IsAsync: Boolean, can be either true or false . The default is false. 

• Mode: value is a constant name from the BindingMode enumeration. For example, {Binding Mode= 0 neWay} . 

• NotifyOnSourceUpdated: Boolean, can be either true or false . The default is false. 


























• NotifyOnTargetUpdated: Boolean, can be either 

true 

or 

false . 

The default is 

false . 







• NotifyOnValidationError: Boolean, can be either 

true 

or 

false 

. The default is 

false 


• Path: a string that describes a path into a data object or a general object model. The format provides several 
different conventions for traversing an object model that cannot be adequately described in this topic. See 
PropertyPath XAML Syntax. 


• RelativeSource: mutually exclusive versus with ElementName and Source; each of these binding properties 
represents a particular binding methodology. See Data Binding Overview. Requires a nested RelativeSource 
MarkupExtension usage to specify the value. 


• Source: mutually exclusive versus RelativeSource and ElementName; each of these binding properties 
represents a particular binding methodology. See Data Binding Overview. Requires a nested extension 
usage, typically a StaticResource Markup Extension that refers to an object data source from a keyed 
resource dictionary. 


• StringFormat: a string that describes a string format convention for the bound data. This is a relatively 
advanced binding concept; see reference page for StringFormat. 

• TargetNullValue; can be set as a bindProp = value string in the expression, but this is dependent on the 
type of the parameter being passed. If passing a reference type for the value, requires an object reference 
such as a nested StaticResource Markup Extension. 


• UpdateSourceTrigger: value is a constant name from the UpdateSourceTrigger enumeration. For example, 
{Binding updateSounceTnigger=LostFocus} . Specific controls potentially have different default values for this 
binding property. See UpdateSourceTrigger. 


ValidatesOnDataErrors: Boolean, can be either true or false . The default is false . See Remarks. 
ValidatesOnExceptions: Boolean, can be either true or false . The default is false . See Remarks. 


• XPath: a string that describes a path into the XMLDOM of an XML data source. See Bind to XML Data Using 
an XMLDataProvider and XPath Queries. 


The following are properties of Binding that cannot be set using the Binding markup extension/ {Binding} 
expression form. 


• UpdateSourceExceptionFilter: this property expects a reference to a callback implementation. 
Callbacks/methods other than event handlers cannot be referenced in XAML syntax. 


• ValidationRules: the property takes a generic collection of ValidationRule objects. This could be expressed 
as a property element in a Binding object element, but has no readily available attribute-parsing technique 
for usage in a Binding expression. See reference topic for ValidationRules. 

• XmlNamespaceManager 


Remarks 


IMPORTANT 

In terms of dependency property precedence, a Binding expression is equivalent to a locally set value. If you set a local 
value for a property that previously had a Binding expression, the Binding is completely removed. For details, see 
Dependency Property Value Precedence. 


Describing data binding at a basic level is not covered in this topic. See Data Binding Overview. 



















NOTE 

MultiBinding and PriorityBinding do not support a XAML extension syntax. You would instead use property elements. See 
reference topics for MultiBinding and PriorityBinding. 


Boolean values for XAML are case insensitive. For example you could specify either 
{Binding NotifyOnValidationEnror=true} Of {Binding NotifyOnValidationError=Tnue} . 

Bindings that involve data validation are typically specified by an explicit Binding element rather than as a 
{Binding ...} expression, and setting ValidatesOnDataErrors or ValidatesOnExceptions in an expression is 
uncommon. This is because the companion property ValidationRules cannot be readily set in the expression form. 
For more information, see Implement Binding Validation. 

Binding is a markup extension. Markup extensions are typically implemented when there is a requirement to 
escape attribute values to be other than literal values or handler names, and the requirement is more global than 
type converters attributed on certain types or properties. All markup extensions in XAML use the { and } 
characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup 
extension must process the string contents. For more information, see Markup Extensions and WPF XAML. 

Binding is an atypical markup extension in that the Binding class that implements the extension functionality for 
WPF's XAML implementation also implements several other methods and properties that are not related to XAML. 
The other members are intended to make Binding a more versatile and self-contained class that can address many 
data binding scenarios in addition to functioning as a XAML markup extension. 

See also 

• Binding 

• Data Binding Overview 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 








ColorConvertedBitmap Markup Extension 

4/24/2020 • 2 minutes to read ^ Edit Online 


Provides a way to specify a bitmap source that does not have an embedded profile. Color contexts / profiles are 
specified by URI, as is the image source URI. 

XAML Attribute Usage 

<object pr'oper'ty="{ColorConver'tedBitmap imageSource sourcellC destinationllC}" ... /> 

XAML Values 


imageSource 

The URI of the nonprofiled bitmap. 

souncellC 

The URI of the source profile configuration. 

destinationllC 

The URI of the destination profile configuration 


Remarks 

This markup extension is intended to fill a related set of image-source property values such as UriSource. 

Attribute syntax is the most common syntax used with this markup extension. ColorConvertedBitmap (or 
coiorConvertedBitmapExtension ) cannot be used in property element syntax, because the values can only be set as 
values on the initial constructor, which is the string following the extension identifier. 

ColorConvertedBitmap is a markup extension. Markup extensions are typically implemented when there is a 
requirement to escape attribute values to be other than literal values or handler names, and the requirement is 
more global than just putting type converters on certain types or properties. All markup extensions in XAML use 
the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that 
a markup extension must process the attribute. For more information, see Markup Extensions and WPF XAML. 

See also 

• UriSource 

• Markup Extensions and WPF XAML 

• Imaging Overview 











ComponentResourceKey Markup Extension 

4/24/2020 • 3 minutes to read ^ Edit Online 


Defines and references keys for resources that are loaded from external assemblies. This enables a resource 
lookup to specify a target type in an assembly, rather than an explicit resource dictionary in an assembly or on a 
class. 

XAML Attribute Usage (setting key, compact) 

<object x:Key="{ComponentResour'ceKey {x:Type targetTypeName}, targetID}" ... /> 


XAML Attribute Usage (setting key verbose) 

<object x:Key="{ComponentResour'ceKey TypeInTargetAssembly={x:Type targetTypeName}^ ResourceID=targetID}" ... 
/> 


XAML Attribute Usage (requesting resource, compact) 

<object property="{DynamicResource {ComponentResourceKey {x:Type targetTypeName}, targetID}}" ... /> 


XAML Attribute Usage (requesting resource, verbose) 

<object property="{DynamicResource (ComponentResourceKey TypeInTargetAssembly={x:Type targetTypeName}, 
ResourceID=targetID}}" ... /> 


XAML Values 


targetTypeName 


The name of the public common language runtime (CLR) type 
that is defined in the resource assembly. 


targetID The key for the resource. When resources are looked up, 

targetID will be analogous to the x:Key Directive of the 
resource. 


Remarks 

As seen in the usages above, a { ComponentResourceKey } markup extension usage is found in two places: 

• The definition of a key within a theme resource dictionary, as provided by a control author. 

• Accessing a theme resource from the assembly, when you are retemplating the control but want to use 
property values that come from resources provided by the control's themes. 


For referencing component resources that come from themes, it is generally recommended that you use 










{DynamicResource} rather than {StaticResource} . This is shown in the usages. {DynamicResounce} is 
recommended because the theme itself can be changed by the user. If you want the component resource that most 
closely matches the control author's intent for supporting a theme, you should enable your component resource 
reference to be dynamic also. 

The TypeInTargetAssembly identifies a type that exists in the target assembly where the resource is actually 
defined. A componentResourceKey can be defined and used independently of knowing exactly where the 
TypeInTargetAssembly is defined, but eventually must resolve the type through referenced assemblies. 

A common usage for ComponentResourceKey is to define keys that are then exposed as members of a class. For 
this usage, you use the ComponentResourceKey class constructor, not the markup extension. For more 
information, see ComponentResourceKey, or the "Defining and Referencing Keys for Theme Resources" section of 
the topic Control Authoring Overview. 

For both establishing keys and referencing keyed resources, attribute syntax is commonly used for the 
ComponentResourceKey markup extension. 

The compact syntax shown relies on the ComponentResourceKey constructor signature and positional parameter 
usage of a markup extension. The order in which the targetiypeName and targetiD are given is important. The 
verbose syntax relies on the ComponentResourceKey parameterless constructor, and then sets the 
TypeInTargetAssembly and Resourceld in a way that is analogous to a true attribute syntax on an object element. In 
the verbose syntax, the order in which the properties are set is not important. The relationship and mechanisms of 
these two alternatives (compact and verbose) is described in more detail in the topic Markup Extensions and WPF 
XAML. 

Technically, the value for targetiD can be any object, it does not have to be a string. However, the most common 
usage in WPF is to align the targetiD value with forms that are strings, and where such strings are valid in the 
XamlName Grammar. 

ComponentResourceKey can be used in object element syntax. In this case, specifying the value of both the 
TypeInTargetAssembly and Resourceld properties is required to properly initialize the extension. 

In the WPF XAML reader implementation, the handling for this markup extension is defined by the 
ComponentResourceKey class. 

ComponentResourceKey is a markup extension. Markup extensions are typically implemented when there is a 
requirement to escape attribute values to be other than literal values or handler names, and the requirement is 
more global than just putting type converters on certain types or properties. All markup extensions in XAML use 
the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes that 
a markup extension must process the attribute. For more information, see Markup Extensions and WPF XAML. 

See also 

• ComponentResourceKey 

• ControlTem plate 

• Control Authoring Overview 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 













DateTime XAML Syntax 

3/12/2020 • 3 minutes to read ^ Edit Online 


Some controls, such as Calendar and DatePicker, have properties that use the DateTime type. Although you 
typically specify an initial date or time for these controls in the code-behind at run time, you can specify an initial 
date or time in XAML. The WPF XAML parser handles parsing of DateTime values using a built-in XAML text syntax. 
This topic describes the specifics of the DateTime XAML text syntax. 

When To Use DateTime XAML Syntax 

Setting dates in XAML is not always necessary and may not even be desirable. For example, you could use the 
DateTime.Now property to initialize a date at run time, or you could do all your date adjustments for a calendar in 
the code-behind based on user input. However, there are scenarios where you may want to hard-code dates into a 
Calendar and DatePicker in a control template. The DateTime XAML syntax must be used for these scenarios. 

DateTime XAML Syntax is a Native Behavior 

DateTime is a class that is defined in the base class libraries of the CLR. Because of how the base class libraries 
relate to the rest of the CLR, it is not possible to apply TypeConverterAttribute to the class and use a type converter 
to process strings from XAML and convert them to DateTime in the run time object model. There is no 
DateTimeConventer class that provides the conversion behavior; the conversion behavior described in this topic is 
native to the WPF XAML parser. 

Format Strings for DateTime XAML Syntax 

You can specify the format of a DateTime with a format string. Format strings formalize the text syntax that can be 
used to create a value. DateTime values for the existing WPF controls generally only use the date components of 
DateTime and not the time components. 

When specifying a DateTime in XAML, you can use any of the format strings interchangeably. 

You can also use formats and format strings that are not specifically shown in this topic. Technically, the XAML for 
any DateTime value that is specified and then parsed by the WPF XAML parser uses an internal call to 
DateTime.Parse, therefore you could use any string accepted by DateTime.Parse for your XAML input. For more 
information, see DateTime.Parse. 


IMPORTANT 

The DateTime XAML syntax always uses en-us as the Cultureinfo for its native conversion. This is not influenced by 
Language value or xml: lang value in the XAML, because XAML attribute-level type conversion acts without that context. 
Do not attempt to interpolate the format strings shown here due to cultural variations, such as the order in which day and 
month appear. The format strings shown here are the exact format strings used when parsing the XAML regardless of other 
culture settings. 


The following sections describe some of the common DateTime format strings. 

Short Date Pattern ("d") 

The following shows the short date format for a DateTime in XAML: 

M/d/YYYY 


This is the simplest form that specifies all necessary information for typical usages by WPF controls, and cannot be 








influenced by accidental time zone offsets versus a time component, and is therefore recommended over the other 
formats. 

For example, to specify the date of June 1,2010, use the following string: 

3/1/2010 

For more information, see DateTimeFormatInfo.ShortDatePattern. 

Sortable DateTime Pattern ("s") 

The following shows the sortable DateTime pattern in XAML: 

yyyy'-'MM'-'dd'T'HH':'mm':'ss 

For example, to specify the date of June 1,2010, use the following string (time components are all entered as 0): 
2010-06-011000:00:00 

RFC1123 Pattern ("r") 

The RFC1123 pattern is useful because it could be a string input from other date generators that also use the 
RFC1123 pattern for culture invariant reasons. The following shows the RFC1123 DateTime pattern in XAML: 

dddj dd MMM yyyy HH':'mm':'ss 'UTC 

For example, to specify the date of June 1,2010, use the following string (time components are all entered as 0): 
Mon, 01 Sun 2010 00:00:00 UTC 

Other Formats and Patterns 

As stated previously, a DateTime in XAML can be specified as any string that is acceptable as input for 
DateTime.Parse. This includes other formalized formats (for example UniversalSortableDateTimePattern), and 
formats that are not formalized as a particular DateTimeFormatInfo form. For example, the form YYYY/mm/dd is 
acceptable as input for DateTime.Parse. This topic does not attempt to describe all possible formats that work, and 
instead recommends the short date pattern as a standard practice. 

See also 


• XAML Overview (WPF) 








DynamicResource Markup Extension 
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Provides a value for any XAML property attribute by deferring that value to be a reference to a defined resource. 
Lookup behavior for that resource is analogous to run-time lookup. 

XAML Attribute Usage 

<object property="{DynamicResour'ce key}" ... /> 


XAML Property Element Usage 


<object> 


cobject.property) 


cDynamicResource ResourceKey="key" . 

.. /) 

</object.property) 


</object) 



XAML Values 


key The key for the requested resource. This key was initially 

assigned by the x:Key Directive if a resource was created in 
markup, or was provided as the key parameter when 
calling ResourceDictionary.Add if the resource was created in 
code. 

Remarks 

A DynamicResource will create a temporary expression during the initial compilation and thus defer lookup for 
resources until the requested resource value is actually required in order to construct an object. This may 
potentially be after the XAML page is loaded. The resource value will be found based on key search against all 
active resource dictionaries starting from the current page scope, and is substituted for the placeholder 
expression from compilation. 


IMPORTANT 

In terms of dependency property precedence, a DynamicResource expression is equivalent to the position where the 
dynamic resource reference is applied. If you set a local value for a property that previously had a DynamicResource 
expression as the local value, the DynamicResource is completely removed. For details, see Dependency Property Value 
Precedence. 


Certain resource access scenarios are particularly appropriate for DynamicResource as opposed to a 
StaticResource Markup Extension. See XAML Resources for a discussion about the relative merits and 
performance implications of DynamicResource and StaticResource . 


The specified ResourceKey should correspond to an existing resource determined by x:Key Directive at some level 











in your page, application, the available control themes and external resources, or system resources, and the 
resource lookup will happen in that order. For more information about resource lookup for static and dynamic 
resources, see XAML Resources. 

A resource key may be any string defined in the XamlName Grammar. A resource key may also be other object 
types, such as a Type. A Type key is fundamental to how controls can be styled by themes. For more information, 
see Control Authoring Overview. 

APIs for lookup of resource values, such as FindResource, follow the same resource lookup logic as used by 
DynamlcResource . 

The alternative declarative means of referencing a resource is as a StaticResource Markup Extension. 

Attribute syntax is the most common syntax used with this markup extension. The string token provided after the 
DynamicResource identifier String is assigned as the ResourceKey value of the underlying 
DynamicResourceExtension extension class. 

DynamicResource can be used in object element syntax. In this case, specifying the value of the ResourceKey 
property is required. 

DynamicResource can also be used in a verbose attribute usage that specifies the ResourceKey property as a 
property=value pair: 

<object property="{DynamicResource ResourceKey=key}" ... /> 

The verbose usage is often useful for extensions that have more than one settable property, or if some properties 
are optional. Because DynamicResource has only one settable property, which is required, this verbose usage is 
not typical. 

In the WPF XAML processor implementation, the handling for this markup extension is defined by the 
DynamicResourceExtension class. 

DynamicResource is a markup extension. Markup extensions are typically implemented when there is a 
requirement to escape attribute values to be other than literal values or handler names, and the requirement is 
more global than just putting type converters on certain types or properties. All markup extensions in XAML use 
the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes 
that a markup extension must process the attribute. For more information, see Markup Extensions and WPF 
XAML. 

See also 

• XAML Resources 

• Resources and Code 

• x:Key Directive 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• StaticResource Markup Extension 

• Markup Extensions and WPF XAML 








RelativeSource MarkupExtension 
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Specifies properties of a RelativeSource binding source, to be used within a Binding Markup Extension, or when 
setting the RelativeSource property of a Binding element established in XAML. 

XAML Attribute Usage 

<Binding RelativeSource="{RelativeSour'ce modeEnumValue}" ... /> 


XAML Attribute Usage (nested within Binding extension) 

<object pr'oper'ty="{Binding RelativeSource={RelativeSource modeEnumValue} ...}" ... /> 


XAML Object Element Usage 

<Binding> 

<Binding.RelativeSource> 

<RelativeSource Mode="modeEnumValue"/> 
</Binding.RelativeSource> 

</Binding> 


-or- 


<Binding> 

<Binding.RelativeSource> 
<RelativeSource 

Mode="FindAncestor" 
AncestorType="{x:Type typeName}" 
AncestorLevel="intLevel" 

/> 

</Binding.RelativeSource> 

</Binding> 


XAML Values 


modeEnumValue One of the following: 

- The string token self ; corresponds to a RelativeSource as 
created with its Mode property set to Self 

- The string token TemplatedParent ; corresponds to a 
RelativeSource as created with its Mode property set to 
TemplatedParent. 

- The string token PreviousData ; corresponds to a 
RelativeSource as created with its Mode property set to 
PreviousData. 

- See below for information on FlndAncestor mode. 










FindAncestor 

The string token 

FindAncestor 

. Using this token enters a 


mode whereby a 

RelativeSource 

specifies an ancestor type 


and optionally an ancestor level. This corresponds to a 
RelativeSource as created with its Mode property set to 
FindAncestor. 

typeName Required for FindAncestor mode. The name of a type, which 

fills the AncestorType property. 

intLevel Optional for FindAncestor mode. An ancestor level 

(evaluated towards the parent direction in the logical tree). 


Remarks 

{RelativeSource TempiatedParent} binding usages are a key technique that addresses a larger concept of the 
separation of a control's Ul and a control's logic. This enables binding from within the template definition to the 
templated parent (the run time object instance where the template is applied). For this case, the TemplateBinding 
Markup Extension is in fact a shorthand for the following binding expression: 

{Binding RelativeSource={RelativeSource TempiatedParent}} . TemplateBinding or 

{RelativeSource TempiatedParent} usages are both only relevant within the XAML that defines a template. For 
more information, see TemplateBinding Markup Extension. 

{RelativeSource FindAncestor} is mainly used in control templates or predictable self-contained Ul compositions, 
for cases where a control is always expected to be in a visual tree of a certain ancestor type. For example, items of 
an items control might use FindAncestor usages to bind to properties of their items control parent ancestor. Or, 
elements that are part of control composition in a template can use FindAncestor bindings to the parent elements 
in that same composition structure. 

In the object element syntax for FindAncestor mode shown in the XAML Syntax sections, the second object 
element syntax is used specifically for FindAncestor mode. FindAncestor mode requires an AncestorType value. 
You must set AncestorType as an attribute using an x:Type Markup Extension reference to the type of ancestor to 
look for. The AncestorType value is used when the binding request is processed at run-time. 

For FindAncestor mode, the optional property AncestorLevel can help disambiguate the ancestor lookup in cases 
where there is possibly more than one ancestor of that type existing in the element tree. 

For more information on how to use the FindAncestor mode, see RelativeSource. 

{RelativeSource Self} is useful for scenarios where one property of an instance should depend on the value of 
another property of the same instance, and no general dependency property relationship (such as coercion) 
already exists between those two properties. Although it is rare that two properties exist on an object such that the 
values are literally identical (and are identically typed), you can also apply a converter parameter to a binding that 
has {RelativeSource Self} , and use the converter to convert between source and target types. Another scenario 
for {RelativeSource Self} is as part of a MultiDataTrigger. 


For example, the following XAML defines a Rectangle element such that no matter what value is entered for Width, 
the Rectangle is always a square: 

<Rectangle Width="200" Fleight="{Binding RelativeSource={RelativeSource Self}j Path=Width}" .../> 


{RelativeSource PreviousData} 

is useful either in data templates, or in cases where bindings are using a collection 

as the data source. You can use 

{RelativeSource PreviousData} 

to highlight relationships between adjacent data 


items in the collection. A related technique is to establish a MultiBinding between the current and previous items 
in the data source, and use a converter on that binding to determine the difference between the two items and 























their properties. 


In the following example, the first TextBlock in the items template displays the current number. The second 
TextBlock binding is a MultiBinding that nominally has two Binding constituents: the current record, and a binding 
that deliberately uses the previous data record by using {ReiativeSource PneviousData} . Then, a converter on the 
MultiBinding calculates the difference and returns it to the binding. 

<ListBox IMame="fibolist"> 

<ListBox.ItemTemplate> 

<DataTemplate> 

<StackPanel Or'ientation="Horizontal"> 

<TextBlocl< Text="{Binding}"/> 

<TextBlocl<>j difference = </TextBlock> 

<TextBlock> 

<TextBlock.Text> 

<MultiBinding Converter="{StaticResource DiffConverter}"> 

<Binding/> 

<Binding RelativeSource="{RelativeSource PreviousData}"/> 

</MultiBinding> 

</TextBlock.Texts 
</TextBlock> 

</StackPanel> 

</DataTemplate> 

</LlstBox.ItemTemplates 
</ListBox> 


Describing data binding as a concept is not covered here, see Data Binding Overview. 

In the WPF XAML processor implementation, the handling for this markup extension is defined by the 
ReiativeSource class. 

ReiativeSource is a markup extension. Markup extensions are typically implemented when there is a requirement 
to escape attribute values to be other than literal values or handler names, and the requirement is more global 
than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } 
characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup 
extension must process the attribute. For more information, see Markup Extensions and WPF XAML. 

See also 

• Binding 

• Styling and Templating 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• Data Binding Overview 

• Binding Declarations Overview 

• x:Type Markup Extension 





StaticResource Markup Extension 
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Provides a value for any XAML property attribute by looking up a reference to an already defined resource. 
Lookup behavior for that resource is analogous to load-time lookup, which will look for resources that were 
previously loaded from the markup of the current XAML page as well as other application sources, and will 
generate that resource value as the property value in the run-time objects. 

XAML Attribute Usage 

<object property="{StaticResource key}" ... /> 


XAML Object Element Usage 


<object> 

<obj ect.property> 

<StaticResource ResourceKey="key" . 

</object.property) 

</object> 

.. /> 


XAML Values 

key 


The key for the requested resource. This key was initially 
assigned by the x:Key Directive if a resource was created in 
markup, or was provided as the key parameter when 
calling ResourceDictionary.Add if the resource was created in 
code. 

Remarks 




IMPORTANT 

A StaticResource must not attempt to make a forward reference to a resource that is defined lexically further within 
the XAML file. Attempting to do so is not supported, and even if such a reference does not fail, attempting the forward 
reference will incur a load time performance penalty when the internal hash tables representing a ResourceDictionary are 
searched. For best results, adjust the composition of your resource dictionaries such that forward references can be 
avoided. If you cannot avoid a forward reference, use DynamicResource Markup Extension instead. 


The specified ResourceKey should correspond to an existing resource, identified with an x:Key Directive at some 
level in your page, application, the available control themes and external resources, or system resources. The 
resource lookup occurs in that order. For more information about resource lookup behavior for static and 
dynamic resources, see XAML Resources. 

A resource key can be any string defined in the XamlName Grammar. A resource key can also be other object 
types, such as a Type. A Type key is fundamental to how controls can be styled by themes, through an implicit 
style key. For more information, see Control Authoring Overview. 










The alternative declarative means of referencing a resource is as a DynamicResource Markup Extension. 

Attribute syntax is the most common syntax used with this markup extension. The string token provided after 
the staticResource identifier string is assigned as the ResourceKey value of the underlying 
StaticResourceExtension extension class. 

StaticResource can be used in object element syntax. In this case, specifying the value of the ResourceKey 
property is required. 

StaticResource can also be used in a verbose attribute usage that specifies the ResourceKey property as a 
property=value pair: 

<object property="{StaticResource ResourceKey=key}" ... /> 

The verbose usage is often useful for extensions that have more than one settable property, or if some 
properties are optional. Because staticResource has only one settable property, which is required, this verbose 
usage is not typical. 

In the WPF XAML processor implementation, the handling for this markup extension is defined by the 
StaticResourceExtension class. 

StaticResource is a markup extension. Markup extensions are typically implemented when there is a 
requirement to escape attribute values to be other than literal values or handler names, and the requirement is 
more global than Just putting type converters on certain types or properties. All markup extensions in XAML 
use the { and } characters in their attribute syntax, which is the convention by which a XAML processor 
recognizes that a markup extension must process the attribute. For more information, see Markup Extensions 
and WPF XAML. 

See also 

• Styling and Templating 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• XAML Resources 

• Resources and Code 








TemplateBinding Markup Extension 

4/24/2020 • 2 minutes to read ^ Edit Online 


Links the value of a property in a control template to be the value of another property on the templated control. 

XAML Attribute Usage 

<object property="{TemplateBinding sounceProperty}" ... /> 


XAML Attribute Usage (for Setter property in template or style) 

<Setter Property="propertyName" Value="{TemplateBinding sourceProperty}" ... /> 


XAML Values 


propertyName 

DependencyProperty.Name of the property being set in the 
setter syntax. 

sourceProperty 

Another dependency property that exists on the type being 


templated, specified by its DependencyProperty.Name. 


- or - 

A "dotted-down" property name that is defined by a different 
type than the target type being templated. This is actually a 
Property Path. See Property Path XAML Syntax. 

Remarks 

A TemplateBinding is an optimized form of a Binding for template scenarios, analogous to a Binding constructed 
with {Binding RelativeSource={RelativeSource TemplatedPanent}, Mode=OneWay} . A TemplateBinding is always a 
one-way binding, even if properties involved default to two-way binding. Both properties involved must be 
dependency properties. In order to achieve two-way binding to a templated parent use the following binding 
statement instead 

{Binding RelativeSounce={RelativeSounce TemplatedPanent}, Mode=TwoWay, Path=MyDependencyProperty} . 

RelativeSource is another markup extension that is sometimes used in conjunction with or instead of 
TemplateBinding in order to perform relative property binding within a template. 

Describing control templates as a concept is not covered here; for more information, see Control Styles and 
Templates. 

Attribute syntax is the most common syntax used with this markup extension. The string token provided after the 
TemplateBinding identifier String is assigned as the Property value of the underlying TemplateBindingExtension 
extension class. 

Object element syntax is possible, but it is not shown because it has no realistic application. TemplateBinding is 
used to fill values within setters, using evaluated expressions, and using object element syntax for 















TempiateBinding to fill <setter'.Property> property element syntax is unnecessarily verbose. 


TempiateBinding can also be used in a verbose attribute usage that specifies the Property property as a 
property=value pair: 

<object property="{TemplateBinding Pr'oper'ty=sourceProperty}" ... /> 

The verbose usage is often useful for extensions that have more than one settable property, or if some properties 
are optional. Because TempiateBinding has only one settable property, which is required, this verbose usage is not 
typical. 

In the WPF XAML processor implementation, the handling for this markup extension is defined by the 
TemplateBindingExtension class. 

TempiateBinding is a markup extension. Markup extensions are typically implemented when there is a 
requirement to escape attribute values to be other than literal values or handler names, and the requirement is 
more global than just putting type converters on certain types or properties. All markup extensions in XAML use 
the { and } characters in their attribute syntax, which is the convention by which a XAML processor recognizes 
that a markup extension must process the attribute. For more information, see Markup Extensions and WPF 
XAML. 

See also 

• Style 

• ControlTemplate 

• Styling and Templating 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• RelativeSource MarkupExtension 

• Binding Markup Extension 
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Provides a way for custom control authors or applications that integrate third-party controls to load theme-specific 
resource dictionaries to use in styling the control. 

XAML Attribute Usage 

<object pr'oper'ty="{ThemeDictionary assemblyUri}" ... /> 


XAML Object Element Usage 

<object> 

<object.property> 

<ThemeDictionary AssemblyName="asseniblyLlri"/> 
<object. pr'oper'ty> 

<object> 


XAML Values 


assemblyUri The uniform resource identifier (URI) of the assembly that 

contains theme information. Typically, this is a pack URI that 
references an assembly in the larger package. Assembly 
resources and pack URIs simplify deployment issues. For more 
information see Pack URIs in WPF. 

Remarks 

This extension is intended to fill only one specific property value: a value for ResourceDictionary.Source. 

By using this extension, you can specify a single resources-only assembly that contains some styles to use only 
when the Windows Aero theme is applied to the user's system, other styles only when the Luna theme is active, 
and so on. By using this extension, the contents of a control-specific resource dictionary can be automatically 
invalidated and reloaded to be specific for another theme when required. 

The assemblyUri String (AssemblyName property value) forms the basis of a naming convention that identifies 
which dictionary applies for a particular theme. The ProvideValue logic for ThemeDictionary completes the 
convention by generating a uniform resource identifier (URI) that points to a particular theme dictionary variant, as 
contained within a precompiled resource assembly. Describing this convention, or theme interactions with general 
control styling and page/application level styling as a concept, is not covered fully here. The basic scenario for 
using ThemeDictionary is to Specify the Source property of a ResourceDictionary declared at the application level. 
When you provide a URI for the assembly through a ThemeDictionary extension rather than as a direct URI, the 
extension logic will provide invalidation logic that applies whenever the system theme changes. 

Attribute syntax is the most common syntax used with this markup extension. The string token provided after the 
ThemeDictionary identifier String is assigned as the AssemblyName value of the underlying 
ThemeDictionaryExtension extension class. 













ThemeDictionany may also be used in object element syntax. In this case, specifying the value of the 
AssemblyName property is required. 

ThemeDictionany can also be used in a verbose attribute usage that specifies the Member property as a 
property=value pair: 

<object pnopenty="{ThemeDictionary AssemblyName=assemblyUri}" ... /> 

The verbose usage is often useful for extensions that have more than one settable property, or if some properties 
are optional. Because ThemeDictionany has only one settable property, which is required, this verbose usage is not 
typical. 

In the WPF XAML processor implementation, the handling for this markup extension is defined by the 
ThemeDictionaryExtension class. 

ThemeDictionany is a markup extension. Markup extensions are typically implemented when there is a requirement 
to escape attribute values to be other than literal values or handler names, and the requirement is more global 
than just putting type converters on certain types or properties. All markup extensions in XAML use the { and } 
characters in their attribute syntax, which is the convention by which a XAML processor recognizes that a markup 
extension must process the attribute. For more information, see Markup Extensions and WPF XAML. 

See also 

• Styling and Templating 

• XAML Overview (WPF) 

• Markup Extensions and WPF XAML 

• WPF Application Resource, Content, and Data Files 







Property Path XAML Syntax 
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The PropertyPath object supports a complex inline XAML syntax for setting various properties that take the 
PropertyPath type as their value. This topic documents the PropertyPath syntax as applied to binding and 
animation syntaxes. 

Where PropertyPath Is Used 

PropertyPath is a common object that is used in several Windows Presentation Foundation (WPF) features. 

Despite using the common PropertyPath to convey property path information, the usages for each feature area 
where PropertyPath is used as a type vary. Therefore, it is more practical to document the syntaxes on a per- 
feature basis. 

Primarily, WPF uses PropertyPath to describe object-model paths for traversing the properties of an object data 
source, and to describe the target path for targeted animations. 

Some style and template properties such as Setter.Property take a qualified property name that superficially 
resembles a PropertyPath. But this is not a true PropertyPath; instead it is a qualified owner.property str'mq format 
usage that is enabled by the WPF XAML processor in combination with the type converter for 
Dependency Property. 

PropertyPath for Objects in Data Binding 

Data binding is a WPF feature whereby you can bind to the target value of any dependency property. However, the 
source of such a data binding need not be a dependency property; it can be any property type that is recognized 
by the applicable data provider. Property paths are particularly used for the ObjectDataProvider, which is used for 
obtaining binding sources from common language runtime (CLR) objects and their properties. 

Note that data binding to XML does not use PropertyPath, because it does not use Path in the Binding. Instead, you 
use XPath and specify valid XPath syntax into the XML Document Object Model (DOM) of the data. XPath is also 
specified as a string, but is not documented here; see Bind to XML Data Using an XMLDataProvider and XPath 
Queries. 

A key to understanding property paths in data binding is that you can target the binding to an individual property 
value, or you can instead bind to target properties that take lists or collections. If you are binding collections, for 
instance binding a ListBox that will expand depending on how many data items are in the collection, then your 
property path should reference the collection object, not individual collection items. The data binding engine will 
match the collection used as the data source to the type of the binding target automatically, resulting in behavior 
such as populating a ListBox with an items array. 

Single Property on the Immediate Object as Data Context 

<Binding Path="propertyName" ... /> 

propertyName must resolve to be the name of a property that is in the current DataContext for a Path usage. If 
your binding updates the source, that property must be read/write and the source object must be mutable. 

Single Indexer on the Immediate Object as Data Context 





<Binding Path="[key]" ... /> 

key must be either the typed index to a dictionary or hash table, or the integer index of an array. Also, the value 
of the key must be a type that is directly bindable to the property where it is applied. For instance, a hash table 
that contains string keys and string values can be used this way to bind to Text for a TextBox. Or, if the key points to 
a collection or subindex, you could use this syntax to bind to a target collection property. Otherwise, you need to 
reference a specific property, through a syntax such as <Binding Path="[key] .propertyName" .../> . 

You can specify the type of the index if necessary. For details on this aspect of an indexed property path, see 
Binding.Path. 

Multiple Property (Indirect Property Targeting) 

<Bindlng Path="propertyName.pr'oper'tyName2" ... /> 

propertyName must resolve to be the name of a property that is the current DataContext. The path properties 
propertyName and propertyName2 can be any properties that exist in a relationship, where propertyName2 is a 
property that exists on the type that is the value of propertyName . 

Single Property, Attached or Otherwise Type-Qualified 

<object property="(ownerType.propertyName)" ... /> 

The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. It 
can use an XML namespace to find the type with an appropriate mapping. The owneriype searches types that a 
XAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. Most 
applications have the default XML namespace mapped to the 

http://schemas.microsoft.com/winfx/2006/xami/presentation namespace, SO a prefix is usually Only necessary for 
custom types or types otherwise outside that namespace. propertyName must resolve to be the name of a 
property existing on the owneriype . This syntax is generally used for one of the following cases: 

• The path is specified in XAML that is in a style or template that does not have a specified Target Type. A 
qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, 
the property exists on an instance, not a type. 

• The property is an attached property. 

• You are binding to a static property. 

For use as storyboard target, the property specified as propertyName must be a DependencyProperty. 

Source Traversal (Binding to Hierarchies of Collections) 

<object Path="propertyName/propertyNameX" ... /> 

The / in this syntax is used to navigate within a hierarchical data source object, and multiple steps into the 
hierarchy with successive / characters are supported. The source traversal accounts for the current record pointer 
position, which is determined by synchronizing the data with the Ul of its view. For details on binding with 
hierarchical data source objects, and the concept of current record pointer in data binding, see Use the Master- 
Detail Pattern with Hierarchical Data or Data Binding Overview. 












NOTE 

Superficially, this syntax resembles XPath. A true XPath expression for binding to an XML data source is not used as a Path 
value and should instead be used for the mutually exclusive XPath property. 


Collection Views 

To reference a panned collection view, prefix the collection view name with the hash character ( # ). 

Current Record Pointer 

To reference the current record pointer for a collection view or master detail data binding scenario, start the path 
string with a forward slash ( / ). Any path past the forward slash is traversed starting from the current record 
pointer. 

Multiple Indexers 

<object Path="[indexljindex2...]" ... /> 

or 

<object Path="pr'oper'tyName[indeXjindex2.. . ... /> 

If a given object supports multiple indexers, those indexers can be specified in order, similar to an array 
referencing syntax. The object in question can be either the current context or the value of a property that contains 
a multiple index object. 

By default, the indexer values are typed by using the characteristics of the underlying object. You can specify the 
type of the index if necessary. For details on typing the indexers, see Binding.Path. 

Mixing Syntaxes 

Each of the syntaxes shown above can be interspersed. For instance, the following is an example that creates a 
property path to the color at a particular x,y of a coiorGrid property that contains a pixel grid array of 
SolidColorBrush objects: 

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColonBrushResult}" ... /> 

Escapes for Property Path Strings 

For certain business objects, you might encounter a case where the property path string requires an escape 
sequence in order to parse correctly. The need to escape should be rare, because many of these characters have 
similar naming-interaction issues in languages that would typically be used to define the business object. 

• Inside indexers ([ ]), the caret character (^) escapes the next character. 

• You must escape (using XML entities) certain characters that are special to the XML language definition. Use 

& to escape the character "8t". Use > to escape the end tag ">". 

• You must escape (using backslash \ ) characters that are special to the WPF XAML parser behavior for 
processing a markup extension. 

o Backslash ( \ ) is the escape character itself. 

o The equal sign ( = ) separates property name from property value. 

o Comma ( , ) separates properties. 







o The right curly brace ( } ) is the end of a markup extension. 


NOTE 

Technically, these escapes work for a storyboard property path also, but you are usually traversing object models for existing 
WPF objects, and escaping should be unnecessary. 


PropertyPath for Animation Targets 

The target property of an animation must be a dependency property that takes either a Freezable or a primitive 
type. However, the targeted property on a type and the eventual animated property can exist on different objects. 
For animations, a property path is used to define the connection between the named animation target object's 
property and the intended target animation property, by traversing object-property relationships in the property 
values. 

General Object-Property Considerations for Animations 

For more information on animation concepts in general, see Storyboards Overview and Animation Overview. 

The value type or the property being animated must be either a Freezable type or a primitive. The property that 
starts the path must resolve to be the name of a dependency property that exists on the specified TargetName 
type. 

In order to support cloning for animating a Freezable that is already frozen, the object specified by TargetName 
must be a FrameworkElement or FrameworkContentElement derived class. 

Single Property on the Target Object 

onimation Storyboard.TargetPr'oper'ty="pr'opertyName" ... /> 

propertyName must resolve to be the name of a dependency property that exists on the specified TargetName 

type- 

indirect Property Targeting 

<animation Storyboard.TargetProperty="propertyName.propertyName2" ... /> 

propertyName must be a property that is either a Freezable value type or a primitive, which exists on the specified 
TargetName type. 

must be the name of a dependency property that exists on the object that is the value of 
. In other words, propertyNamez must exist as a dependency property on the type that is the 
PropertyType. 

Indirect targeting of animations is necessary because of applied styles and templates. In order to target an 
animation, you need a TargetName on a target object, and that name is established by x:Name or Name. Although 
template and style elements also can have names, those names are only valid within the namescope of the style 
and template. (If templates and styles did share namescopes with application markup, names couldn't be unique. 
The styles and templates are literally shared between instances and would perpetuate duplicate names.) Thus, if 
the individual properties of an element that you might wish to animate came from a style or template, you need 
to start with a named element instance that is not from a style template, and then target into the style or template 
visual tree to arrive at the property you wish to animate. 

For instance, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that came from 
a theme template. To animate a Brush completely, there would need to be a BrushAnimation (probably one for 


propertyNamez 

propertyName 

propertyName 



every Brush type) and there is no such type. To animate a Brush, you instead animate properties of a particular 
Brush type. You need to get from SolidColorBrush to its Color to apply a ColorAnimation there. The property path 
for this example would be Background.color . 

Attached Properties 

onimation Storyboard.TargetProperty="(ownerType.propertyName)" ... /> 

The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. It 
can use an XML namespace to find the type. The owneriype searches types that a XAML processor has access to, 
through the XmlnsDefinitionAttribute declarations in each assembly. Most applications have the default XML 
namespace mapped to the http://schemas.microsoft.com/winfx/ 2006 /xami/presentation namespace, so a prefix is 
usually only necessary for custom types or types otherwise outside that namespace. propertyName must resolve 
to be the name of a property existing on the owneriype . The property specified as propertyName must be a 
DependencyProperty. (All WPF attached properties are implemented as dependency properties, so this issue is 
only of concern for custom attached properties.) 

I ndexers 

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyNameB" ... /> 

Most dependency properties or Freezable types do not support an indexer. Therefore, the only usage for an 
indexer in an animation path is at an intermediate position between the property that starts the chain on the 
named target and the eventual animated property. In the provided syntax, that is propertyName 2 . For instance, an 
indexer usage might be necessary if the intermediate property is a collection such as TransformGroup, in a 
property path such as RenderTransform.Children[l].Angle . 

PropertyPath in Code 

Code usage for PropertyPath, including how to construct a PropertyPath, is documented in the reference topic for 
PropertyPath. 

In general, PropertyPath is designed to use two different constructors, one for the binding usages and simplest 
animation usages, and one for the complex animation usages. Use the PropertyPath(Object) signature for binding 
usages, where the object is a string. Use the PropertyPath(Object) signature for one-step animation paths, where 
the object is a DependencyProperty. Use the PropertyPath(String, Objectf]) signature for complex animations. This 
latter constructor uses a token string for the first parameter and an array of objects that fill positions in the token 
string to define a property path relationship. 

See also 

• PropertyPath 

• Data Binding Overview 

• Storyboards Overview 
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Sets the IsFrozen state to true on the containing Freezable element. Default behavior for a Freezable without the 
PresentationOptions: Freeze attribute specified is that IsFrozen is false at load time, and dependent on general 
Freezable behavior at runtime. 

XAML Attribute Usage 

<object 

xmlns:PresentationOptions="http://schemas.microsoft.com/winfx/2006/xaml/presentation/options" 
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
me:Ignorable="PresentationOptions"> 

<freezableElement PresentationOptions:Freeze="true"/> 

</object> 


XAML Values 


PresentationOptions An XML namespace prefix, which can be any valid prefix string, 

per the XML 1.0 specification. The prefix 
PresentationOptions is used for identification purposes in 
this documentation. 


freezableElement 


An element that instantiates any derived class of Freezable. 


Remarks 

The Freeze attribute is the only attribute or other programming element defined in the 

http://schemas.microsoft.com/winfx/2006/xaml/presentation/options XML namespace. The Freeze attribute exists 
in this special namespace specifically so that it can be designated as ignorable, using mcilgnorable Attribute as part 
of the root element declarations. The reason that Freeze must be able to be ignorable is because not all XAML 
processor implementations are able to freeze a Freezable at load time; this capability is not part of the XAML 
specification. 

The ability to process the Freeze attribute is specifically built in to the XAML processor that processes XAML for 
compiled applications. The attribute is not supported by any class, and the attribute syntax is not extensible or 
modifiable. If you are implementing your own XAML processor you can choose to parallel the freezing behavior of 
the WPF XAML processor when processing the Freeze attribute on Freezable elements at load time. 

Any value for the Freeze attribute other than true (not case sensitive) generates a load time error. (Specifying the 
Freeze attribute as false is not an error, but that is already the default, SO Setting to false does nothing). 

See also 

• Freezable 

• Freezable Objects Overview 

• mcilgnorable Attribute 
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In This Section 

mc:lgnorable Attribute 
mc:ProcessContent Attribute 




mclgnorable Attribute 
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Specifies which XML namespace prefixes encountered in a markup file may be ignored by a XAML processor. The 
mc:ignor'abie attribute supports markup compatibility both for custom namespace mapping and for XAML 
versioning. 

XAML Attribute Usage (Single Prefix) 

<object 

xmlns: ignorablePreflx="ignor'ableLlr'i" 

xtnlns :mc=" http: //schemas, openxmlformats .org/markup-compatibility/2006" 
me:Ignorable="ignorablePrefix"...> 

<ignor'ablePr'efixl:ThisElementCanBeIgnored/> 

</object> 


XAML Attribute Usage (Two Prefixes) 

<object 

xmlns:ignorablePreflxl="ignorableUrl" 
xmlns:ignorablePrefix2="ignorableUri2" 

xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
me:Ignorable="ignorablePrefixl ignorablePrefix2"...> 
<ignorablePrefixl:ThisElementCanBeIgnored/> 

</object> 


XAML Values 


ignorablePrefix, ignorablePrefIxl, etc. 

Any valid prefix string, per the XML 1.0 specification. 

ignorabteUri 

Any valid URI for designating a namespace, per the XML 1.0 
specification. 

ThisElementCanBeIgnored 

An element that can be ignored by Extensible Application 

Markup Language (XAML) processor implementations, if the 
underlying type cannot be resolved. 

Remarks 

The me XML namespace prefix is the recommended prefix convention to use when mapping the XAML 

compatibility namespace http://schemas. 

.openxmlformats.org/markup-compatibility/2006 . 


Elements or attributes where the prefix portion of the element name are identified as me: ignorabie will not raise 
errors when processed by a XAML processor. If that attribute could not be resolved to an underlying type or 
programming construct, then that element is ignored. Note however that ignored elements might still generate 
additional parsing errors for additional element requirements that are side effects of that element not being 
processed. For instance, a particular element content model might require exactly one child element, but if the 
specified child element was in an me:ignorabie prefix, and the specified child element could not be resolved to a 











type, then the XAML processor might raise an error. 

mc:ignor'abie only applies to namespace mappings to identifier Strings, mcrignorabie does not apply to 
namespace mappings into assemblies, which specify a CLR namespace and an assembly (or default to the current 
executable as the assembly). 

If you are implementing a XAML processor, your processor implementation must not raise parsing or processing 
errors on type resolution for any element or attribute that is qualified by a prefix that is identified as mc:ignor'abie 
. But your processor implementation can still raise exceptions that are a secondary result of an element failing to 
load or be processed, such as the one-child element example given earlier. 

By default, a XAML processor will ignore content within an ignored element. However, you can specify an 
additional attribute, mciProcessContent Attribute, to require continued processing of content within an ignored 
element by the next available parent element. 

Multiple prefixes can be specified in the attribute, using one or more white-space characters as the separator, for 
example: mc:Ignorable="ignor'el ignor'e2" . 

The http://schemas.openxmifor'mats.org/markup-compatibiiity/2006 namespace defines Other elements and 
attributes that are not documented within this area of the SDK. For more information, see XML Markup 
Compatibility Specification. 

See also 

• XamIReader 

• PresentationOptions:Freeze Attribute 

• XAML Overview (WPF) 

• Documents in WPF 
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Specifies which XAML elements should still have content processed by relevant parent elements, even if the 
immediate parent element may be ignored by a XAML processor due to specifying mc:lgnorable Attribute. The 
attribute supports markup compatibility both for custom namespace mapping and for XAML 


XAML Attribute Usage 

<object 

xmlns: ignorablePrefix="ignor'ableLlr'i" 

xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
me: Ignor'able="ignorablePrefix". .. 

me: ProcessContent="ignor'ablePrefix:ThisElementCanBeIgnored" 

> 

<ignor'ablePr'efix:ThisElementCanBeIgnor'ed> 

[content] 

</ignorablePrefix:ThisElementCanBeIgnored> 

</object> 


me:ProcessContent 

versioning. 


XAML Values 


igrorablePrefix 


Any valid prefix string, per the XML 1.0 specification. 


ignorableUri 


Any valid URI for designating a namespace, per the XML 1.0 
specification. 


ThisElementCanBelgnored An element that can be ignored by Extensible Application 

Markup Language (XAML) processor implementations, if the 
underlying type cannot be resolved. 


[content] ThisElementCanBelgnored \s marked ignorable. If the 

processor ignores that element, [content] \s processed by 
object. 


Remarks 

processor will ignore content within an ignored element. You can specify a specific element by 
, and a XAML processor will continue to process the content within the ignored element. This 
would typically be used if the content is nested within several tags, at least one of which is ignorable and at least 
one of which is not ignorable. 

Multiple prefixes may be specified in the attribute, using a space separator, for example: 

mc:ProcessContent="ignore:Elementl ignore:Element2" . 

The http://schemas.openxmiformats.org/markup-compatibiiity/2006 namespace defines Other elements and 
attributes that are not documented within this area of the SDK. For more information, see XML Markup 
Compatibility Specification. 


By default, a XAML 

me:ProcessContent 









See also 

• mc:lgnorable Attribute 

• XAML Overview (WPF) 
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Four key classes— UlElement, ContentElement, FrameworkElement, and FrameworkContentElement— implement a 
substantial percentage of the common element functionality available in WPF programming. These four classes 
are referred to in this SDK as the base element classes. 

In This Section 

Base Elements Overview 
Freezable Objects Overview 
Alignment, Margins, and Padding Overview 
How-to Topics 

Reference 

UlElement 

ContentElement 

FrameworkElement 

FrameworkContentElement 

Related Sections 

WPF Architecture 
XAMLinWPF 

Element Tree and Serialization 

Properties 

Events 

Input 

Resources 

Styling and Templating 
Threading Model 
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A high percentage of classes in Windows Presentation Foundation (WPF) are derived from four classes which are 
commonly referred to in the SDK documentation as the base element classes. These classes are UlElement, 
FrameworkElement, ContentElement, and FrameworkContentElement. The DependencyObject class is also related, 
because it is a common base class of both UlElement and ContentElement 

Base Element APIs in WPF Classes 

Both UlElement and ContentElement are derived from DependencyObject, through somewhat different pathways. 
The split at this level deals with how a UlElement or ContentElement are used in a user interface and what 
purpose they serve in an application. UlElement also has Visual in its class hierarchy, which is a class that exposes 
the lower-level graphics support underlying the Windows Presentation Foundation (WPF). Visual provides a 
rendering framework by defining independent rectangular screen regions. In practice, UlElement is for elements 
that will support a larger object model, are intended to render and layout into regions that can be described as 
rectangular screen regions, and where the content model is deliberately more open, to allow different 
combinations of elements. ContentElement does not derive from Visual; its model is that a ContentElement would 
be consumed by something else, such as a reader or viewer that would then interpret the elements and produce 
the complete Visual for Windows Presentation Foundation (WPF) to consume. Certain UlElement classes are 
intended to be content hosts: they provide the hosting and rendering for one or more ContentElement classes 
(DocumentViewer is an example of such a class). ContentElement is used as base class for elements with 
somewhat smaller object models and that more address the text, information, or document content that might be 
hosted within a UlElement. 

Framework-Level and Core-Level 

UlElement serves as the base class for FrameworkElement, and ContentElement serves as the base class for 
FrameworkContentElement. The reason for this next level of classes is to support a WPF core level that is separate 
from a WPF framework level, with this division also existing in how the APIs are divided between the 
PresentationCore and PresentationFramework assemblies. The WPF framework level presents a more complete 
solution for basic application needs, including the implementation of the layout manager for presentation. The 
WPF core level provides a way to use much of WPF without taking the overhead of the additional assembly. The 
distinction between these levels very rarely matters for most typical application development scenarios, and in 
general you should think of the WPF APIs as a whole and not concern yourself with the difference between WPF 
framework level and WPF core level. You might need to know about the level distinctions if your application 
design chooses to replace substantial quantities of WPF framework level functionality, for instance if your overall 
solution already has its own implementations of user interface (Ul) composition and layout. 

Choosing Which Element to Derive From 

The most practical way to create a custom class that extends WPF is by deriving from one of the WPF classes 
where you get as much as possible of your desired functionality through the existing class hierarchy. This section 
lists the functionality that comes with three of the most important element classes to help you decide which class 
to inherit from. 

If you are implementing a control, which is really one of the more common reasons for deriving from a WPF class, 
you probably want to derive from a class that is a practical control, a control family base class, or at least from the 
Control base class. For some guidance and practical examples, see Control Authoring Overview. 

If you are not creating a control and need to derive from a class that is higher in the hierarchy, the following 




sections are intended as a guide for what characteristics are defined in each base element class. 

If you create a class that derives from DependencyObject, you inherit the following functionality: 

• GetValue and SetValue support, and general property system support 

• Ability to use dependency properties and attached properties that are implemented as dependency 
properties. 

If you create a class that derives from UlElement you inherit the following functionality in addition to that 
provided by DependencyObject 

• Basic support for animated property values. For more information, see Animation Overview. 

• Basic input event support and commanding support. For more information, see Input Overview and 
Commanding Overview. 

• Virtual methods that can be overridden to provide information to a layout system. 

If you create a class that derives from FrameworkElement you inherit the following functionality in addition to 
that provided by UlElement 

• Support for styling and storyboards. For more information, see Style and Storyboards Overview. 

• Support for data binding. For more information, see Data Binding Overview. 

• Support for dynamic resource references. For more information, see XAML Resources. 

• Property value inheritance support and other flags in the metadata that help report conditions about 
properties to framework services such as data binding, styles, or the framework implementation of layout 
For more information, see Framework Property Metadata. 

• The concept of the logical tree. For more information, see Trees in WPF. 

• Support for the practical WPF framework-level implementation of the layout system, including an 
OnPropertyChanged override that can detect changes to properties that influence layout 

If you create a class that derives from ContentElement you inherit the following functionality in addition to that 
provided by DependencyObject 

• Support for animations. For more information, see Animation Overview. 

• Basic input event support and commanding support. For more information, see Input Overview and 
Commanding Overview. 

If you create a class that derives from FrameworkContentElement you get the following functionality in addition 
to that provided by ContentElement 

• Support for styling and storyboards. For more information, see Style and Animation Overview. 

• Support for data binding. For more information, see Data Binding Overview. 

• Support for dynamic resource references. For more information, see XAML Resources. 

• Property value inheritance support and other flags in the metadata that help report conditions about 
properties to framework services like data binding, styles, or the framework implementation of layout For 
more information, see Framework Property Metadata. 

• You do not inherit access to layout system modifications (such as ArrangeOverride). Layout system 
implementations are only available on FrameworkElement However, you inherit an OnPropertyChanged 
override that can detect changes to properties that influence layout and report these to any content hosts. 


Content nnodels are documented for a variety of classes. The content model for a class is one possible factor you 
should consider if you want to find an appropriate class to derive from. For more information, see WPF Content 
Model. 

Other Base Classes 

DispatcherObject 

DispatcherObject provides support for the WPF threading model and enables all objects created for WPF 
applications to be associated with a Dispatcher. Even if you do not derive from UlElement, DependencyObject, or 
Visual, you should consider deriving from DispatcherObject in order to get this threading model support. For 
more information, see Threading Model. 

Visual 

Visual implements the concept of a 2D object that generally requires visual presentation in a roughly rectangular 
region. The actual rendering of a Visual happens in other classes (it is not self-contained), but the Visual class 
provides a known type that is used by rendering processes at various levels. Visual implements hit testing, but it 
does not expose events that report hit-testing positives (these are in UlElement). For more information, see Visual 
Layer Programming. 

Freezable 

Freezable simulates immutability in a mutable object by providing the means to generate copies of the object 
when an immutable object is required or desired for performance reasons. The Freezable type provides a 
common basis for certain graphics elements such as geometries and brushes, as well as animations. Notably, a 
Freezable is not a Visual; it can hold properties that become subproperties when the Freezable is applied to fill a 
property value of another object, and those subproperties might affect rendering. For more information, see 
Freezable Objects Overview. 

Animatable 

Animatable is a Freezable derived class that specifically adds the animation control layer and some utility 
members so that currently animated properties can be distinguished from nonanimated properties. 

Control 

Control is the intended base class for the type of object that is variously termed a control or component, 
depending on the technology. In general, WPF control classes are classes that either directly represent a Ul control 
or participate closely in control composition. The primary functionality that Control enables is control templating. 

See also 

• Control 

• Dependency Properties Overview 

• Control Authoring Overview 

• WPF Architecture 


Freezable Objects Overview 
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This topic describes how to effectively use and create Freezable objects, which provide special features that can 
help improve application performance. Examples of freezable objects include brushes, pens, transformations, 
geometries, and animations. 

What Is a Freezable? 

A Freezable is a special type of object that has two states: unfrozen and frozen. When unfrozen, a Freezable 
appears to behave like any other object. When frozen, a Freezable can no longer be modified. 

A Freezable provides a Changed event to notify observers of any modifications to the object. Freezing a Freezable 
can improve its performance, because it no longer needs to spend resources on change notifications. A frozen 
Freezable can also be shared across threads, while an unfrozen Freezable cannot. 

Although the Freezable class has many applications, most Freezable objects in Windows Presentation Foundation 
(WPF) are related to the graphics sub-system. 

The Freezable class makes it easier to use certain graphics system objects and can help improve application 
performance. Examples of types that inherit from Freezable include the Brush, Transform, and Geometry classes. 
Because they contain unmanaged resources, the system must monitor these objects for modifications, and then 
update their corresponding unmanaged resources when there is a change to the original object. Even if you don't 
actually modify a graphics system object, the system must still spend some of its resources monitoring the object, 
in case you do change it. 

For example, suppose you create a SolidColorBrush brush and use it to paint the background of a button. 

Button myButton = new Button(); 

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow); 
myButton.Background = myBrush; 


Dim myButton As New Button() 

Dim myBrush As New SolidColorBrush(Colors.Yellow) 
myButton.Background = myBrush 

When the button is rendered, the WPF graphics sub-system uses the information you provided to paint a group 
of pixels to create the appearance of a button. Although you used a solid color brush to describe how the button 
should be painted, your solid color brush doesn't actually do the painting. The graphics system generates fast, 
low-level objects for the button and the brush, and it is those objects that actually appear on the screen. 

If you were to modify the brush, those low-level objects would have to be regenerated. The freezable class is what 
gives a brush the ability to find its corresponding generated, low-level objects and to update them when it 
changes. When this ability is enabled, the brush is said to be "unfrozen." 

A freezable's Freeze method enables you to disable this self-updating ability. You can use this method to make the 
brush become "frozen," or unmodifiable. 






{ 

// Makes the brush unmodiftable, 
my Brush. Freeze 0; 

} 


If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.Freeze() 

End If 


When you no longer need to modify a freezable, freezing it provides performance benefits. If you were to freeze 
the brush in this example, the graphics system would no longer need to monitor it for changes. The graphics 
system can also make other optimizations, because it knows the brush won't change. 


NOTE 

For convenience, freezable objects remain unfrozen unless you explicitly freeze them. 


Using Freezables 

Using an unfrozen freezable is like using any other type of object. In the following example, the color of a 
SolidColorBrush is changed from yellow to red after it's used to paint the background of a button. The graphics 
system works behind the scenes to automatically change the button from yellow to red the next time the screen is 
refreshed. 


Button myButton = new Button(); 

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow); 
myButton.Background = myBrush; 

// Changes the button's background to red. 
myBrush.Color = Colors.Red; 


Dim myButton As New Button() 

Dim myBrush As New SolidColorBrush(Colors.Yellow) 
myButton.Background = myBrush 

' Changes the button's background to red. 
myBrush.Color = Colors.Red 


Freezing a Freezable 

To make a Freezable unmodifiable, you call its Freeze method. When you freeze an object that contains freezable 
objects, those objects are frozen as well. For example, if you freeze a PathGeometry, the figures and segments it 
contains would be frozen too. 


A Freezable can't be frozen if any of the following are true: 






• It has animated or data bound properties. 

• It has properties set by a dynamic resource. (See the XAML Resources for more information about dynamic 
resources.) 

• It contains Freezable sub-objects that can't be frozen. 

If these conditions are false, and you don't intend to modify the Freezable, then you should freeze it to gain the 
performance benefits described earlier. 

Once you call a freezable's Freeze method, it can no longer be modified. Attempting to modify a frozen object 
causes an InvalidOperationException to be thrown. The following code throws an exception, because we attempt 
to modify the brush after it's been frozen. 

Button myButton = new Button(); 

SolidColorBnush myBnush = new SolidColonBrush(Colors.Yellow); 

if (myBnush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
myBnush. Freeze 0; 

} 

myButton.Background = myBrush; 
try { 

// Throws an InvalidOperationExceptionj because the brush is frozen. 
myBrush.Color = Colors.Red; 

}catch(InvalidOperationException ex) 

{ 

MessageBox.Show("Invalid operation: " + ex.ToStringO); 

} 


Dim myButton As New Button() 

Dim myBrush As New SolidColorBrush(Colors.Yellow) 

If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.Freeze() 

End If 

myButton.Background = myBrush 
Try 

' Throws an InvalidOperationException, because the brush is frozen. 
myBrush.Color = Colors.Red 
Catch ex As InvalidOperationException 

MessageBox.Show("Invalid operation: " & ex.ToStringO) 

End Try 


To avoid throwing this exception, you can use the IsFrozen method to determine whether a Freezable is frozen. 



Button myButton = new Button(); 

SolidColonBnush myBnush = new SolidColonBrush(Colors.Yellow)j 

if (myBnush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
my Brush. FneezeO; 

} 

myButton.Background = myBnush; 

if (myBnush.IsFrozen) // Evaluates to true. 

{ 

// If the brush is frozen^ create a clone and 
// modify the clone. 

SolidColorBrush myBrushClone = myBrush.Clone()j 
myBrushClone.Color = Colors.Red; 
myButton.Background = myBrushClone; 

} 

else 

{ 

// If the brush is not frozen^ 

// it can be modified directly. 
myBnush.Color = Colors.Red; 

} 


Dim myButton As New Button() 

Dim myBnush As New SolidColorBrush(Colors.Yellow) 

If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.FreezeO 
End If 

myButton.Background = myBrush 

If myBrush.IsFrozen Then ' Evaluates to true. 

' If the brush is frozen, create a clone and 
' modify the clone. 

Dim myBrushClone As SolidColorBrush = myBrush.Clone() 
myBrushClone.Color = Colors.Red 
myButton.Background = myBrushClone 

Else 

' If the brush is not frozen, 

' it can be modified directly. 
myBrush.Color = Colors.Red 
End If 


In the preceding code example, a modifiable copy was made of a frozen object using the Clone method. The next 
section discusses cloning in more detail. 



NOTE 

Because a frozen freezable cannot be animated, the animation system will automatically create modifiable clones of frozen 
Freezable objects when you try to animate them with a Storyboard. To eliminate the performance overhead caused by 
cloning, leave an object unfrozen if you intend to animate it. For more information about animating with storyboards, see 
the Storyboards Overview. 


Freezing from Markup 

To freeze a Freezable object declared in markup, you use the Pr’esentationOptions:Fr’eeze attribute. In the 
following example, a SolidColorBrush is declared as a page resource and frozen. It is then used to set the 
background of a button. 

<Page 

xmlns="http: //schemas. micr'osoft. com/winfx/2006/xaml/pr'esentation" 
xmlns: x="http: //schemas. micr'osoft. com/winfx/2006/xaml" 

xmlns: PresentationOptions="http: //schemas. micr’osoft. com/winfx/2006/xaml/pr'esentation/options" 
xmlns :mc=" http: //schemas, openxmlformats •or’g/markup-compatibility/2006" 
me:Ignonable="PnesentationOptions"> 

<Page.Resources> 

<!-- This resource is frozen. --> 

<SolidColorBrush 
x:Key="MyBrush" 

PresentationOptions:Freeze="True" 

Color="Red" /> 

</Page.Resources> 

<StackPanel> 

<Button Content="A Button" 

Background="{StaticResource MyBrush}"> 

</Button> 

</StackPanel> 

</Page> 

To use the Freeze attribute, you must map to the presentation options namespace: 
http://schemas.microsoft.com/winfx/2006/xaml/presentation/options . PresentationOptions is the recommended 
prefix for mapping this namespace: 

xmlns:PresentationOptions="http://schemas.microsoft.com/winfx/2006/xaml/presentation/options" 


Because not all XAML readers recognize this attribute, it's recommended that you use the mc:lgnorable Attribute 
to mark the Presentation:Freeze attribute as ignorable: 

xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" 
me:Ignorable="PresentationOptions" 

For more information, see the mc:lgnorable Attribute page. 

"Unfreezing" a Freezable 

Once frozen, a Freezable can never be modified or unfrozen; however, you can create an unfrozen clone using the 
Clone or CloneCurrentValue method. 


In the following example, the button's background is set with a brush and that brush is then frozen. An unfrozen 









copy is made of the brush using the Clone method. The clone is modified and used to change the button's 
background from yellow to red. 

Button myButton = new Button(); 

SolidColonBnush myBnush = new SolldColonBrush(Colors.Yellow)j 

// Freezing a Freezable before it provides 
// performance improvements if you don't 
// intend on modifying it. 
if (myBrush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
my Brush. FreezeO; 

} 

myButton.Background = myBrush; 

// If you need to modify a frozen brushy 
// the Clone method can be used to 
// create a modifiable copy. 

SolidColorBrush myBrushClone = myBrush.Clone()j 

// Changing myBrushClone does not change 
// the color of myButton^ because its 
// background is still set by myBrush. 
myBrushClone.Color = Colors.Red; 

// Replacing myBrush with myBrushClone 
// makes the button change to red. 
myButton.Background = myBrushClone; 


Dim myButton As New Button() 

Dim myBrush As New SolidColorBrush(Colors.Yellow) 

' Freezing a Freezable before it provides 
' performance improvements if you don't 
' intend on modifying it. 

If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.FreezeO 
End If 


myButton.Background = myBrush 

' If you need to modify a frozen brushy 
' the Clone method can be used to 
' create a modifiable copy. 

Dim myBrushClone As SolidColorBrush = myBrush.Clone() 

' Changing myBrushClone does not change 
' the color of rnyButton^ because its 
' background is still set by myBrush. 
myBrushClone.Color = Colors.Red 

' Replacing myBrush with myBrushClone 
' makes the button change to red. 
myButton.Background = myBrushClone 


NOTE 

Regardless of which clone method you use, animations are never copied to the new Freezable. 




The Clone and CloneCurrentValue methods produce deep copies of the freezable. If the freezable contains other 
frozen freezable objects, they are also cloned and made modifiable. For example, if you clone a frozen 
PathGeometry to make it modifiable, the figures and segments it contains are also copied and made modifiable. 

Creating Your Own Freezable Class 

A class that derives from Freezable gains the following features. 

• Special states: a read-only (frozen) and a writable state. 

• Thread safety: a frozen Freezable can be shared across threads. 

• Detailed change notification: Unlike other DependencyObJects, Freezable objects provide change 
notifications when sub-property values change. 

• Easy cloning: the Freezable class has already implemented several methods that produce deep clones. 

A Freezable is a type of DependencyObJect, and therefore uses the dependency property system. Your class 
properties don't have to be dependency properties, but using dependency properties will reduce the amount of 
code you have to write, because the Freezable class was designed with dependency properties in mind. For more 
information about the dependency property system, see the Dependency Properties Overview. 

Every Freezable subclass must override the CreatelnstanceCore method. If your class uses dependency properties 
for all its data, you're finished. 

If your class contains non-dependency property data members, you must also override the following methods: 

• CloneCore 

• CloneCurrentValueCore 

• GetAsFrozenCore 

• GetCurrentValueAsFrozenCore 

• FreezeCore 

You must also observe the following rules for accessing and writing to data members that are not dependency 
properties: 

• At the beginning of any API that reads non-dependency property data members, call the ReadPreamble 
method. 

• At the beginning of any API that writes non-dependency property data members, call the WritePreamble 
method. (Once you've called WritePreamble in an API, you don't need to make an additional call to 
ReadPreamble if you also read non-dependency property data members.) 

• Call the WritePostscript method before exiting methods that write to non-dependency property data 
members. 

If your class contains non-dependency-property data members that are DependencyObJect objects, you must 
also call the OnFreezablePropertyChanged method each time you change one of their values, even if you're 
setting the member to null . 


NOTE 

It's very important that you begin each Freezable method you override with a call to the base implementation. 


For an example of a custom Freezable class, see the Custom Animation Sample. 




See also 


• Freezable 

• Custom Animation Sample 

• Dependency Properties Overview 

• Custom Dependency Properties 
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The FrameworkElement class exposes several properties that are used to precisely position child elements. This 
topic discusses four of the most important properties: HorizontalAlignment, Margin, Padding, and 
VerticalAlignment. The effects of these properties are important to understand, because they provide the basis for 
controlling the position of elements in Windows Presentation Foundation (WPF) applications. 

Introduction to Element Positioning 

There are numerous ways to position elements using WPF. However, achieving ideal layout goes beyond simply 
choosing the right Panel element. Fine control of positioning requires an understanding of the 
HorizontalAlignment, Margin, Padding, and VerticalAlignment properties. 

The following illustration shows a layout scenario that utilizes several positioning properties. 


Alignment, Margin and Padding Sample 

Button 1 I 

Button 2 

Button 3 


At first glance, the Button elements in this illustration may appear to be placed randomly. However, their positions 
are actually precisely controlled by using a combination of margins, alignments, and padding. 

The following example describes how to create the layout in the preceding illustration. A Border element 
encapsulates a parent StackPanel, with a Padding value of 15 device independent pixels. This accounts for the 
narrow LightBlue band that surrounds the child StackPanel. Child elements of the StackPanel are used to illustrate 
each of the various positioning properties that are detailed in this topic. Three Button elements are used to 
demonstrate both the Margin and HorizontalAlignment properties. 







// Create the application's main Window. 
mainWindow = new Window (); 

mainWindow.Title = "MarginSj Padding and Alignment Sample"; 

// Add a Border 
myBorder = new Border(); 
myBorder.Background = Brushes.LightBlue; 
myBorder.BorderBrush = Brushes.Black; 
myBorder.Padding = new Thickness(15); 
myBorder.BorderThickness = new Thickness(2); 

myStackPanel = new StackPanel(); 
myStackPanel.Background = Brushes.White; 

myStackPanel.HorizontalAlignment = HorizontalAlignment.Center 
myStackPanel.VerticalAlignment = VerticalAlignment.Top; 

TextBlock myTextBlock = new TextBlock(); 
myTextBlock.Margin = new Thickness(5j 0j 5, 0); 
myTextBlock.FontSize = 18; 

myTextBlock.HorizontalAlignment = HorizontalAlignment.Center; 
myTextBlock.Text = "Alignmentj Margin and Padding Sample"; 
Button myButtonl = new Button(); 

myButtonl.HorizontalAlignment = HorizontalAlignment.Left; 
myButtonl.Margin = new Thickness(20); 
myButtonl.Content = "Button 1"; 

Button myButtonl = new Button(); 

myButtonl.HorizontalAlignment = HorizontalAlignment.Right; 
myButtonl.Margin = new Thickness(10); 
myButtonl.Content = "Button 2"; 

Button myButtonB = new Button(); 

myButtonB.HorizontalAlignment = HorizontalAlignment.Stretch; 
myButtonB.Margin = new Thickness(0); 
myButtonB.Content = "Button 3"; 

// Add child elements to the parent StackPanel. 
myStackPanel.Children.Add(myTextBlock); 
myStackPanel.Children.Add(myButtonl); 
myStackPanel.Children.Add(myButton!); 
myStackPanel.Children.Add(myButtons); 

// Add the StackPanel as the lone Child of the Border. 
myBorder.Child = myStackPanel; 

// Add the Border as the Content of the Parent Window Object. 
mainWindow.Content = myBorder; 
mainWindow.Show (); 



WindowTitle = "ManginSj Padding and Alignment Sample" 

'Add a Bonder. 

Dim myBorden As New Borden() 
myBorder.Background = Brushes.LightBlue 
myBorder.BorderBrush = Brushes.Black 
myBorder.Padding = New Thickness(15) 
myBorder.BorderThickness = New Thickness(2) 

Dim myStackPanel As New StackPanel() 
myStackPanel.Background = Brushes.White 

myStackPanel.HorizontalAlignment = Windows.HorizontalAlignment.Center 
myStackPanel.VerticalAlignment = Windows.VerticalAlignment.Top 

Dim myTextBlock As New TextBlock() 
myTextBlock.Margin = New Thickness(5, 0, 5, 0) 
myTextBlock.FontSize = 18 

myT extBlock.HorizontalAlignment = Windows.HorizontalAlignment.Center 
myTextBlock.Text = "Alignmentj Margin and Padding Sample" 

Dim myButtonl As New Button() 

myButtonl.HorizontalAlignment = Windows.HorizontalAlignment.Left 
myButtonl.Margin = New Thickness(20) 
myButtonl.Content = "Button 1" 

Dim myButtonl As New Button() 

myButtonl.HorizontalAlignment = Windows.HorizontalAlignment.Right 
myButtonl.Margin = New Thickness(10) 
myButtonl.Content = "Button 2" 

Dim myButtonB As New Button() 

myButtonB.HorizontalAlignment = Windows.HorizontalAlignment.Stretch 
myButtonB.Margin = New Thickness(0) 
myButtonB.Content = "Button 3" 

'Add child elements to the parent StackPanel. 
myStackPanel.Children.Add(myTextBlock) 
myStackPanel.Children.Add(myButtonl) 
myStackPanel.Children.Add(myButtonl) 
myStackPanel.Children.Add(myButtons) 

'Add the StackPanel as the lone Child of the Border. 
myBorder.Child = myStackPanel 

' Add the Canvas as the lone Child of the Border 
myBorder.Child = myStackPanel 
Me.Content = myBorder 


The following diagram provides a close-up view of the various positioning properties that are used in the 
preceding sample. Subsequent sections in this topic describe in greater detail how to use each positioning 
property. 
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Understanding Alignment Properties 

The HorizontalAlignment and VerticalAlignnnent properties describe how a child element should be positioned 
within a parent element's allocated layout space. By using these properties together, you can position child 
elements precisely. For example, child elements of a DockPanel can specify four different horizontal alignments: 
Left, Right, or Center, or to Stretch to fill available space. Similar values are available for vertical positioning. 


NOTE 

Explicitly-set Height and Width properties on an element take precedence over the Stretch property value. Attempting to set 
Height, Width, and a HorizontalAlignment value of stretch results in the stretch request being ignored. 


HorizontalAlignment Property 

The HorizontalAlignment property declares the horizontal alignment characteristics to apply to child elements. The 
following table shows each of the possible values of the HorizontalAlignment property. 

MEMBER DESCRIPTION 

Left Child elements are aligned to the left of the parent element's 

allocated layout space. 

Center Child elements are aligned to the center of the parent 

element's allocated layout space. 

Right Child elements are aligned to the right of the parent element's 

allocated layout space. 


Stretch (Default) Child elements are stretched to fill the parent element's 

allocated layout space. Explicit Width and Height values take 
precedence. 

The following example shows how to apply the HorizontalAlignment property to Button elements. Each attribute 
value is shown, to better illustrate the various rendering behaviors. 

Button myButtonl = new Button(); 

myButtonl.HorizontalAlignment = HorizontalAlignment.Left; 
myButtonl.Content = "Button 1 (Left)"; 

Button myButtonZ = new Button(); 

myButtonZ.HorizontalAlignment = HorizontalAlignment.Right; 
myButtonZ.Content = "Button 2 (Right)"; 

Button myButtonB = new Button(); 

myButtonB.HorizontalAlignment = HorizontalAlignment.Center; 
myButtonB.Content = "Button 3 (Center)"; 

Button myButtonA = new Button(); 

myButtonA.HorizontalAlignment = HorizontalAlignment.Stretch; 
myButtonA.Content = "Button 4 (Stretch)"; 




Dim myButtonl As New Button() 

myButtonl.HorizontalAlignment = Windows.HorizontalAlignment.Left 
myButtonl.Margin = New Thickness(20) 
myButtonl.Content = "Button 1" 

Dim myButton2 As New Button() 

myButton2.HorizontalAlignment = Windows.HorizontalAlignment.Right 
myButton2.Margin = New Thicl<ness(10) 
myButton2.Content = "Button 2" 

Dim myButtonS As New Button() 

myButtonS.HorizontalAlignment = Windows.HorizontalAlignment.Center 
myButtonB.Margin = New Thicl<ness(0) 
myButtonB.Content = "Button 3" 

Dim myButtonA As New Button() 

myButtonA.HorizontalAlignment = Windows.HorizontalAlignment.Stretch 
myButtonA.Content = "Button 4 (Stretch)" 


The preceding code yields a layout similar to the following image. The positioning effects of each 
HorizontalAlignment value are visible in the illustration. 


HorizontalAlignment Sample 

Button 1 (Left) | 

Button 2 (Right) 
Button 3 (Center) j 
Button 4 (stretch) 


VerticalAlignment Property 

The VerticalAlignment property describes the vertical alignment characteristics to apply to child elements. The 
following table shows each of the possible values for the VerticalAlignment property. 

MEMBER DESCRIPTION 

Top Child elements are aligned to the top of the parent element's 

allocated layout space. 


Center 


Child elements are aligned to the center of the parent 
element's allocated layout space. 


Bottom 


Child elements are aligned to the bottom of the parent 
element's allocated layout space. 


Stretch (Default) Child elements are stretched to fill the parent element's 

allocated layout space. Explicit Width and Height values take 
precedence. 


The following example shows how to apply the VerticalAlignment property to Button elements. Each attribute 
value is shown, to better illustrate the various rendering behaviors. For purposes of this sample, a Grid element 
with visible gridlines is used as the parent, to better illustrate the layout behavior of each property value. 






TextBlock myTextBlock = new TextBlock(); 
myTextBlock.FontSize = 18; 

myTextBlock.HorizontalAlignment = HorizontalAlignment.Center; 
myTextBlock.Text = "VerticalAlignment Sample"; 
Grid.SetRow(myTextBlockj 0); 

Button myButtonl = new Button(); 

myButtonl.VerticalAlignment = VerticalAlignment.Top; 
myButtonl.Content = "Button 1 (Top)"; 

Grid.SetRow(myButtonl, 1); 

Button myButtonl = new Button(); 

myButtonl.VerticalAlignment = VerticalAlignment.Bottom; 
myButtonl.Content = "Button 1 (Bottom)"; 
Grid.SetRow(myButtonlj 1); 

Button myButtonB = new Button(); 

myButtonB.VerticalAlignment = VerticalAlignment.Center; 
myButtonB.Content = "Button 3 (Center)"; 
Grid.SetRow(myButton3j 3); 

Button myButtonA = new Button(); 

myButtonA.VerticalAlignment = VerticalAlignment.Stretch; 
myButtonA.Content = "Button 4 (Stretch)"; 
Grid.SetRow(myButton4, 4); 


Dim myTextBlock As New TextBlock() 
myTextBlock.FontSize = 18 

myT extBlock.HorizontalAlignment = Windows.HorizontalAlignment.Center 
myTextBlock.Text = "VerticalAlignment Sample" 
Grid.SetRow(myTextBlockj 0) 

Dim myButtonl As New Button() 

myButtonl.VerticalAlignment = Windows.VerticalAlignment.Top 
myButtonl.Content = "Button 1 (Top)" 

Grid.SetRow(myButtonl, 1) 

Dim myButtonl As New Button() 

myButtonl.VerticalAlignment = Windows.VerticalAlignment.Bottom 
myButtonl.Content = "Button 1 (Bottom)" 

Grid.SetRow(myButtonlj 1) 

Dim myButton3 As New Button() 

myButtonl.VerticalAlignment = Windows.VerticalAlignment.Center 
myButtonl.Content = "Button 3 (Center)" 

Grid.SetRow(myButton3j 3) 

Dim myButtonA As New Button() 

myButtonA.VerticalAlignment = Windows.VerticalAlignment.Stretch 
myButtonA.Content = "Button 4 (Stretch)" 

Grid.SetRow(myButton4j 4) 



<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

WindowTitle="VertlcalAlignment Sample"> 

<Border Background="LlghtBlue" BorderBrush="Black" BorderThickness="2" Padding="15"> 

<Grid Background="White" ShowGridLines="True"> 

<Grid.RowDefinitions> 

<RowDeflnitlon Height="25"/> 

<RowDeflnition Height="50"/> 

<RowDefinition Height="50"/> 

<RowDefinition Height="50"/> 

<RowDeflnition Height="50"/> 

</Grid.RowDefinitions> 

<TextBlock Grid.Row="0" Grid.Column="0" FontSize="18" 

HorizontalAlignment="Center">VerticalAlignment Sample</TextBlock> 

<Button Grid.Row="l" Grid.Column="0" VerticalAlignment="Top">Button 1 (Top)</Button> 

<Button Grid.Row="2" Grid.Column="0" VerticalAlignment="Bottom">Button 2 (Bottom)</Button> 
<Button Grid.Row="3" Grid.Column="0" VerticalAlignment="Center">Button 3 (Center)</Button> 
<Button Grid.Row="4" Grid.Column="0" VerticalAlignment="Stretch">Button 4 (Stretch)</Button> 

</Grid> 

</Border> 

</Page> 


The preceding code yields a layout similar to the following image. The positioning effects of each 
VerticalAlignment value are visible in the illustration. 


Vertic alAlignment Sample 

Button 1 (Top) 



Understanding Margin Properties 

The Margin property describes the distance between an element and its child or peers. Margin values can be 
uniform, by using syntax like Margin="20" . With this syntax, a uniform Margin of 20 device independent pixels 
would be applied to the element. Margin values can also take the form of four distinct values, each value 
describing a distinct margin to apply to the left, top, right, and bottom (in that order), like Margin="0,i0,5,25" . 
Proper use of the Margin property enables very fine control of an element's rendering position and the rendering 
position of its neighbor elements and children. 


NOTE 

A non-zero margin applies space outside the element's ActualWidth and ActualHeight. 


The following example shows how to apply uniform margins around a group of Button elements. The Button 
elements are spaced evenly with a ten-pixel margin buffer in each direction. 




















Button'' myButton? = gcnew Button(); 
myButton7->Mangin = Thickness(10); 
myButton7->Content = "Button 7"; 
Button'' myButtonS = gcnew Button(); 
myButton8->Mangin = Thickness(10); 
myButtonS->Content = "Button 8"; 
Button'' myButton9 = gcnew Button(); 
myButton9->Mangln = Thickness(10); 
myButton9->Content = "Button 9"; 


Button myButton7 = new Button(); 
myButton7.Margin = new Thickness(10); 
myButton7.Content = "Button 7"; 

Button myButtonS = new Button(); 
myButtonS.Margin = new Thickness(10); 
myButtonS.Content = "Button 8"; 

Button myButton9 = new Button(); 
myButton9.Margin = new Thickness(10); 
myButton9.Content = "Button 9"; 


Dim myButton7 As Mew Button 
myButton7.Margin = New Thickness(10) 
myButton7.Content = "Button 7" 

Dim myButtonS As New Button 
myButtonS.Margin = New Thickness(10) 
myButtonS.Content = "Button 8" 

Dim myButton9 As New Button 
myButton9.Margin = New Thickness(10) 
myButton9.Content = "Button 9" 


<Button Margin="10">Button 7</Button> 
<Button Margin="10">Button 8</Button> 
<Button Margin="10">Button 9</Button> 


In many instances, a uniform margin is not appropriate. In these cases, non-uniform spacing can be applied. The 
following example shows how to apply non-uniform margin spacing to child elements. Margins are described in 
this order: left, top, right, bottom. 

Button'' myButtonl = gcnew Button(); 
myButtonl->Margin = Thickness(0j 10, 0, 10); 
myButtonl->Content = "Button 1"; 

Button'' myButtonl = gcnew Button(); 
myButtonl->Margin = Thickness(0j 10j 0, 10); 
myButtonl->Content = "Button 1"; 

Button'' myButtonS = gcnew Button(); 
myButtonS->Margin = Thickness(0j 10j 0, 10); 


Button myButtonl = 

new ButtonO; 




myButtonl.Margin = 

new Thickness(0j 

10, 

0. 

10); 

myButtonl.Content ^ 

= "Button 1"; 




Button myButtonl = 

new ButtonO; 




myButtonl.Margin = 

new Thickness(0^ 

10, 

0. 

10); 

myButtonl.Content ^ 

= "Button 1"; 




Button myButtonS = 

new ButtonO; 




myButtonS.Margin = 

new Thickness(0, 

10, 

0, 

10); 




Dim myButtonl As New Button 

myButtonl.Margin = New Thickness(0j 10^ 8, 10) 
myButtonl.Content = "Button 1" 

Dim myButtonl As New Button 

myButtonl.Margin = New Thicl<ness(0j 10^ 0, 10) 
myButtonl.Content = "Button 1" 

Dim myButtonB As New Button 

myButtonB.Margin = New Thicl<ness(0, 10, 0, 10) 


<Button Margin="0,10,0,10">Button l</Button> 
<Button Margin="0,10,0,10">Button l</Button> 
<Button Margin="0,10,0,10">Button 3</Button> 


Understanding the Padding Property 

Padding is similar to Margin in most respects. The Padding property is exposed on only on a few classes, primarily 
as a convenience: Block, Border, Control, and TextBlock are samples of classes that expose a Padding property. The 
Padding property enlarges the effective size of a child element by the specified Thickness value. 

The following example shows how to apply Padding to a parent Border element. 

myBorder = gcnew Border(); 
myBorder->Bacl<ground = Brushes:: LightBlue; 
myBorder->BorderBrush = Brushes::Black; 
myBorder->BorderThickness = Thickness(l); 
myBorder->CornerRadius = CornerRadius(45); 
myBorder->Padding = Thickness(15); 


myBorder = new Border(); 
myBorder.Background = Brushes.LightBlue; 
myBorder.BorderBrush = Brushes.Black; 
myBorder.BorderThickness = new Thickness(l); 
myBorder.CornerRadius = new CornerRadius(45); 
myBorder.Padding = new Thickness(15); 


Dim myBorder As New Border 
myBorder.Background = Brushes.LightBlue 
myBorder.BorderBrush = Brushes.Black 
myBorder.BorderThickness = New Thickness(l) 
myBorder.CornerRadius = New CornerRadius(45) 
myBorder.Padding = New Thickness(15) 


<Border Background="LightBlue" 
BorderBrush="Black" 
BorderThickness="l" 
CornerRadius="45" 
Padding="15"> 


Using Alignment, Margins, and Padding in an Application 

HorizontalAlignment, Margin, Padding, and VerticalAlignment provide the positioning control necessary to create a 
complex user interface (Ul). You can use the effects of each property to change child-element positioning, enabling 
flexibility in creating dynamic applications and user experiences. 




The following example demonstrates each of the concepts that are detailed in this topic. Building on the 
infrastructure found in the first sample in this topic, this example adds a Grid element as a child of the Border in 
the first sample. Padding is applied to the parent Border element. The Grid is used to partition space between three 
child StackPanel elements. Button elements are again used to show the various effects of Margin and 
HorizontalAlignment. TextBlock elements are added to each ColumnDefinition to better define the various 
properties applied to the Button elements in each column. 

mainWindow = gcnew Window(); 

myBorden = gcnew Bonder(); 
myBorden->Bacl<gnound = Brushes:: LightBlue; 
myBorder->BorderBrush = Brushes::Black; 
myBorder->BorderThickness = Thickness(2); 
myBorder->CornerRadius = CornerRadius(45); 
myBorder->Padding = Thickness(25); 

// Define the Grid. 
myGrid = gcnew Grid(); 
myGrid->Background = Brushes::White; 
myGrid->ShowGridLines = true; 

// Define the Columns. 

ColumnDefinition* myColDefl = gcnew ColumnDefinition(); 
myColDefl->Width = GridLength(l, GridUnitType::Auto); 

ColumnDefinition* myColDef2 = gcnew ColumnDefinition(); 
myColDef2->Width = GridLength(l, GridUnitType::Star); 

ColumnDefinition* myColDefB = gcnew ColumnDefinition(); 
myColDef3->Width = GridLength(l, GridUnitType::Auto); 

// Add the ColumnDefinitions to the Grid. 
myGrid->ColumnDefinitions->Add(myColDef1); 
myGrid->ColumnDefinitions->Add(myColDef2); 
myGrid->ColumnDefinitions->Add(myColDef3); 

// Add the first child StackPanel. 

StackPanel* myStackPanel = gcnew StackPanel(); 
myStackPanel->HorizontalAlignment = HorizontalAlignment::Left; 
myStackPanel->VerticalAlignment = VerticalAlignment::Top; 

Grid::SetColumn(myStackPanel, 0); 

Grid::SetRow(myStackPanelj 0); 

TextBlock* myTextBlockl = gcnew TextBlock(); 
myTextBlockl-xFontSize = 18; 

myTextBlockl-xHorizontalAlignment = HorizontalAlignment::Center; 
myTextBlockl-xMargin = Thickness(0, 0, 0, 15); 
myTextBlockl->Text = "StackPanel 1"; 

Button* myButtonl = gcnew Button(); 
myButtonl->Margin = Thickness(0, 10, 0, 10); 
myButtonl->Content = "Button 1"; 

Button* myButton2 = gcnew Button(); 
myButtonl->Margin = Thickness(0, 10, 0, 10); 
myButtonl->Content = "Button 2"; 

Button* myButton3 = gcnew Button(); 
myButton3->Margin = Thickness(0, 10, 0, 10); 

TextBlock* myTextBlockl = gcnew TextBlock(); 
myTextBlock2->Text = "ColumnDefinition.Width = \"Auto\""; 

TextBlock* myTextBlockl = gcnew TextBlock(); 

myTextBlock3->Text = "StackPanel.HorizontalAlignment = \"Left\""; 

TextBlock* myTextBlockA = gcnew TextBlock(); 
myTextBlock4->Text = "StackPanel.VerticalAlignment = \"Top\""; 

TextBlock* myTextBlockl = gcnew TextBlock(); 
myTextBlock5->Text = "StackPanel.Orientation = \"Vertical\""; 

TextBlock* myTextBlockS = gcnew TextBlock(); 
myTextBlock6->Text = "Button.Margin = \"1,10,0,10\""; 
myStackPanel->Children->Add(myTextBlockl); 
myStackPanel->Children->Add(myButtonl); 
myStackPanel->Children->Add(myButton!); 


myStackPanel->Childr'en->Add( my Buttons); 
myStackPanel->Children->Add(myTextBlock2); 
myStackPanel->Children->Add(myTextBlocks); 
myStackPanel->Childnen->Add(myTextBlock4); 
myStackPanel->Childnen->Add(myTextBlock5); 
myStackPanel->Children->Add(myTextBlocks); 

// Add the second child StackPanel. 

StackPanel'' myStackPanel2 = gcnew StackPanel(); 

myStackPanel2->HonizontalAlignment = HorizontalAlignment::Stretch; 
myStackPanel2->VerticalAlignment = VerticalAlignment::Top; 
myStackPanel2->0rientation = Orientation:rVertical; 

Grid::SetColumn(myStackPanel2j 1); 

Grid::SetRow(myStackPanel2j 0); 

TextBlock'' myTextBlock? = gcnew TextBlock(); 
myTextBlock7->FontSize = 18; 

myTextBlock7->HorizontalAlignment = HorizontalAlignment::Center; 
myTextBlock7->Margin = Thickness(0j 0, 0, 15); 
myTextBlock7->Text = "StackPanel 2"; 

Button'' myButtonA = gcnew Button(); 
myButton4->Margln = Thickness(10, 0, 10, 0); 
myButton4->Content = "Button 4"; 

Button'' myButtonB = gcnew Button(); 
myButton5->Margin = Thickness(10j 0, 10, 0); 
myButton5->Content = "Button 5"; 

Button'' myButtonS = gcnew Button(); 
myButton6->Margin = Thickness(10j 0, 10, 0); 
myButton6->Content = "Button 6"; 

TextBlock'' myTextBlockS = gcnew TextBlock(); 

myTextBlockS-xHorizontalAlignment = HorizontalAlignment::Center; 
myTextBlock8->Text = "ColumnDefinition.Width = 

TextBlock'' myTextBlockg = gcnew TextBlock(); 

myTextBlock9->HorizontalAlignment = HorizontalAlignment::Center; 
myTextBlock9->Text = "StackPanel.HorizontalAlignment = \"Stretch\"" 
TextBlock'' myTextBlockl0 = gcnew TextBlock(); 

myTextBlockl0->HorizontalAlignment = HorizontalAlignment::Center; 
myTextBlockl0->Text = "StackPanel.VerticalAlignment = \"Top\""; 
TextBlock'' myTextBlockll = gcnew TextBlock(); 

myTextBlockll->HorizontalAlignment = HorizontalAlignment::Center; 
myTextBlockll->Text = "StackPanel.Orientation = \"Horizontal\""; 
TextBlock'' myTextBlockl2 = gcnew TextBlock(); 

myTextBlockl2->HorizontalAlignment = HorizontalAlignment::Center; 
myTextBlockl2->Text = "Button.Margin = \"10,0jl0j0\""; 
myStackPanel2->Children->Add(myTextBlock7); 
myStackPanel2->Children->Add(myButton4); 
myStackPanel2->Children->Add(myButton5); 
myStackPanel2->Children->Add(myButton6); 
myStackPanel2->Children->Add(myTextBlocks); 
myStackPanel2->Children->Add(myTextBlock9); 
myStackPanel2->Children->Add(myTextBlockl0); 
myStackPanel2->Children->Add(myTextBlockll); 
myStackPanel2->Children->Add(myTextBlockl2); 

// Add the final child StackPanel. 

StackPanel'' myStackPanelS = gcnew StackPanel(); 
myStackPanelS->HorizontalAlignment = HorizontalAlignment::Left; 
myStackPanelS-xVerticalAlignment = VerticalAlignment::Top; 

Grid::SetColumn(myStackPanelSj 2); 

Grid::SetRow(myStackPanelS^ 0); 

TextBlock'' myTextBlocklS = gcnew TextBlock(); 
myTextBlocklS->FontSize = 18; 

myTextBlocklS->HorizontalAllgnment = HorizontalAlignment::Center; 
myTextBlocklS->Margin = Thickness(0j 0, 0, 15); 
myTextBlocklS->Text = "StackPanel S"; 

Button'' myButton7 = gcnew Button(); 
myButton7->Margin = Thickness(10); 
myButton7->Content = "Button 7"; 

Button'' myButtonS = gcnew Button(); 
myButton8->Margin = Thickness(10); 


myButton8->Content = "Button 8"; 

Button'' myButton9 = gcnew Button(); 
myButton9->Mangln = Thickness(10); 
myButton9->Content = "Button 9"; 

TextBlock'' myTextBlockl4 = gcnew TextBlock()j 
myTextBlockl4->Text = "ColumnDefinition.Width = \"Auto\""; 
TextBlock'' myTextBlocklS = gcnew TextBlock()j 

myTextBlockl5->Text = "StackPanel.HorizontalAlignment = \"Left\"' 
TextBlock'' myTextBlocklS = gcnew TextBlock()j 
myTextBlockl6->Text = "StackPanel.VerticalAlignment = \"Top\""j 
TextBlock'' myTextBlockl7 = gcnew TextBlock()j 
myTextBlockl7->Text = "StackPanel.Orientation = \"Vertical\""; 
TextBlock'' myTextBlocklS = gcnew TextBlock()j 
myTextBlockl8->Text = "Button.Margin = \"10\""j 
myStackPanel3->Children->Add(myTextBlockl3); 
myStackPanel3->Children->Add(myButton7); 
myStackPanel3->Children->Add(myButtons); 
myStackPanel3->Children->Add(myButton9); 
myStackPanel3->Children->Add(myTextBlockl4); 
myStackPanel3->Children->Add(myTextBlockl5); 
myStackPanel3->Children->Add(myTextBlockl6); 
myStackPanel3->Children->Add(myTextBlockl7); 
myStackPanel3->Children->Add(myTextBlockl8); 

// Add child content to the parent Grid. 
myGrid->Children->Add(myStackPanel); 
myGrid->Children->Add(myStackPanel2); 
myGrid->Children->Add(myStackPanel3); 

// Add the Grid as the lone child of the Border. 
myBorder->Child = myGrid; 

// Add the Border to the Window as Content and show the Window. 
mainWindow-xContent = myBorder; 

mainWindow->Title = "MargiOj Padding, and Alignment Sample"; 
mainWindow->Show(); 


mainWindow = new Window(); 

myBorder = new Border(); 
myBorder.Background = Brushes.LightBlue; 
myBorder.BorderBrush = Brushes.Black; 
myBorder.BorderThickness = new Thickness(2); 
myBorder.CornerRadius = new CornerRadius(45); 
myBorder.Padding = new Thickness(25); 

// Define the Grid. 
myGrid = new Grid(); 
myGrid.Background = Brushes.White; 
myGrid.ShowGridLines = true; 

// Define the Columns. 

ColumnDefinition myColDefl = new ColumnDefinition(); 
myColDefl.Width = new GridLength(l, GridUnitType.Auto); 
ColumnDefinition myColDef2 = new ColumnDefinition(); 
myColDef2.Width = new GridLength(l, GridUnitType.Star); 
ColumnDefinition myColDefS = new ColumnDefinition(); 
myColDef3.Width = new GridLength(l, GridUnitType.Auto); 

// Add the ColumnDefinitions to the Grid. 
myGrid.ColumnDefinitions.Add(myColDefl); 
myGrid.ColumnDefinitions.Add(myColDef2); 
myGrid.ColumnDefinitions.Add(myColDef3); 

// Add the first child StackPanel. 

StackPanel myStackPanel = new StackPanel(); 
myStackPanel.HorizontalAlignment = HorizontalAlignment.Left; 


myStackPanel.VenticalAlignment = VenticalAlignment.Topj 
Gnid-SetColumnCmyStackPanelj 0); 

Gr'id.SetRow(myStackPanelj 0); 

TextBlock myTextBlockl = new TextBlock(); 
myTextBlockl.FontSize = 18; 

myTextBlockl.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlockl.Margin = new Thickness(0j 0, 0, 15); 
myTextBlockl.Text = "StackPanel 1"; 

Button myButtonl = new Button(); 

myButtonl.Margin = new Thickness(0^ 10^ 0, 10); 

myButtonl.Content = "Button 1"; 

Button myButton2 = new Button(); 

myButton2.Margin = new Thickness(0, 10^ 0j 10); 

myButton2.Content = "Button 2"; 

Button myButtonB = new Button(); 

myButtonB.Margin = new Thickness(0j 10^ 0j 10); 

TextBlock myTextBlock2 = new TextBlock(); 
myTextBlock2.Text = @"ColumnDeflnitlon.Width = ""Auto"""; 
TextBlock myTextBlockB = new TextBlock(); 

myTextBlockB.Text = @"StackPanel.HonizontalAlignment = ""Left""" 
TextBlock myTextBlockA = new TextBlock(); 

myTextBlockA.Text = @"StackPanel.VenticalAlignment = ""Top"""; 
TextBlock myTextBlockS = new TextBlock(); 

myTextBlockS.Text = @"StackPanel.Orientation = ""Vertical"""; 
TextBlock myTextBlockS = new TextBlock(); 
myTextBlockS.Text = @"Button.Margin = ""1^10^0^10"""; 
myStackPanel.Children.Add(myTextBlockl); 
myStackPanel.Children.Add(myButtonl); 
myStackPanel.Children.Add(myButton2); 
myStackPanel.Children.Add(myButtonB); 
myStackPanel.Children.Add(myTextBlock2); 
myStackPanel.Children.Add(myTextBlocks); 
myStackPanel.Children.Add(myTextBlockA); 
myStackPanel.Children.Add(myTextBlockS); 
myStackPanel.Children.Add(myTextBlockS); 

// Add the second child StackPanel. 

StackPanel myStackPanel2 = new StackPanel(); 

myStackPanel2.HonizontalAlignment = HonizontalAlignment.Stretch; 
myStackPanel2.VenticalAlignment = VenticalAlignment.Top; 
myStackPanel2.Orientation = Orientation.Vertical; 

Grid.SetColumn(myStackPanel2, 1); 

Grid.SetRow(myStackPanel2j 0); 

TextBlock myTextBlock? = new TextBlock(); 
myTextBlock?.FontSize = 18; 

myTextBlock?.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlock?.Margin = new Thickness(0j 0, 0j 15); 
myTextBlock?.Text = "StackPanel 2"; 

Button myButtonA = new Button(); 

myButtonA.Margin = new Thickness(10j 0^ 10^ 0); 

myButtonA.Content = "Button 4"; 

Button myButtonS = new Button(); 

myButtonB.Margin = new Thickness(10j 0^ 10^ 0); 

myButtonB.Content = "Button 5"; 

Button myButtonS = new Button(); 

myButtonS.Margin = new Thickness(10j 0^ 10^ 0); 

myButtonS.Content = "Button S"; 

TextBlock myTextBlockS = new TextBlock(); 

myTextBlockS.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlockS.Text = @"ColumnDeflnition.Width = 

TextBlock myTextBlockS = new TextBlock(); 

myTextBlockS.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlockS.Text = @"StackPanel.HonizontalAlignment = ""Stretch 
TextBlock myTextBlockl0 = new TextBlock(); 

myTextBlockl0.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlockl0.Text = @"StackPanel.VenticalAlignment = ""Top"""; 
TextBlock myTextBlockll = new TextBlock(); 

myTextBlockll.HonizontalAlignment = HonizontalAlignment.Center; 
myTextBlockll.Text = @"StackPanel.Orientation = ""Horizontal"""; 










TextBlock myTextBlockl2 = new TextBlock(); 

myTextBlockl2.HorizontalAlignment = HorizontalAlignment.Center 

myTextBlockl2.Text = @"Button.Margin = ""10,0,10^0"""; 

myStackPanel2.Children.Add(myTextBlock?); 

myStackPanel2.Children.Add(myButtonA); 

myStackPanel2.Children.Add(myButtons); 

myStackPanel2.Children.Add(myButtons); 

myStackPanel2.Children.Add(myTextBlockS); 

myStackPanel2.Children.Add(myTextBlock9); 

myStackPanel2.Children.Add(myTextBlocklB); 

myStackPanel2.Children.Add(myTextBlockll); 

myStackPanel2.Children.Add(myTextBlockl2); 

// Add the final child StackPanel. 

StackPanel myStackPanelB = new StackPanel(); 
myStackPanelB.HorizontalAlignment = HorizontalAlignment.Left; 
myStackPanelB.VerticalAlignment = VerticalAlignment.Top; 
Grid.SetColumn(myStackPanel3, 2); 

Grid.SetRow(myStackPanel3j 0); 

TextBlock myTextBlockl3 = new TextBlock(); 
myTextBlockl3.FontSize = 18; 

myTextBlockl3.HorizontalAlignment = HorizontalAlignment.Center 
myTextBlockl3.Margin = new Thickness(0j 0, 0, 15); 
myTextBlockl3.Text = "StackPanel 3"; 

Button myButton7 = new Button(); 
myButton?.Margin = new Thickness(10); 
myButton?.Content = "Button 7"; 

Button myButtonS = new Button(); 
myButtonS.Margin = new Thickness(10); 
myButtonS.Content = "Button 8"; 

Button myButtonS = new Button(); 
myButtonS.Margin = new Thickness(10); 
myButtonS.Content = "Button S"; 

TextBlock myTextBlocklA = new TextBlock(); 
myTextBlocklA.Text = @"ColumnDefinition.Width = ""Auto"""; 
TextBlock myTextBlocklS = new TextBlock(); 

myTextBlocklB.Text = @"StackPanel.HorizontalAlignment = ""Left 
TextBlock myTextBlocklS = new TextBlock(); 

myTextBlocklS.Text = @"StackPanel.\/erticalAlignment = ""Top""" 
TextBlock myTextBlockl7 = new TextBlock(); 

myTextBlockl7.Text = @"StackPanel.Orientation = ""Vertical"""; 

TextBlock myTextBlocklS = new TextBlock(); 

myTextBlocklS.Text = @"Button.Margin = 

myStackPanel3.Children.Add(myTextBlocklS); 

myStackPanelS.Children.Add(myButton7); 

myStackPanelS.Children.Add(myButtonS); 

myStackPanelB.Children.Add(myButtonS); 

myStackPanelB.Children.Add(myTextBlocklA); 

myStackPanelS.Children.Add(myTextBlocklS); 

myStackPanelS.Children.Add(myTextBlocklS); 

myStackPanel3.Children.Add(myTextBlockl?); 

myStackPanel3.Children.Add(myTextBlocklS); 

// Add child content to the parent Grid. 
myGrid.Children.Add(myStackPanel); 
myGrid.Children.Add(myStackPanel2); 
myGrid.Children.Add(myStackPanel3); 

// Add the Grid as the lone child of the Border. 
myBorder.Child = myGrid; 

// Add the Border to the Window as Content and show the Window 
mainWindow.Content = myBorder; 

mainWindow.Title = "Margin^ Paddings and Alignment Sample"; 
mainWindow.Show(); 








Dim myBorder As New Borden 
myBorder.Background = Brushes.LightBlue 
myBorder.BorderBrush = Brushes.Black 
myBorder.BorderThickness = New Thickness(2) 
myBorder.CornerRadius = New CornerRadius(45) 
myBorder.Padding = New Thickness(25) 

'Define the Grid. 

Dim myGrid As New Grid 

myGrid.Background = Brushes.White 

myGrid.ShowGridLines = True 

'Define the Columns. 

Dim myColDefl As New ColumnDefinition 

myColDefl.Width = New GridLength(l, GridUnitType.Auto) 

Dim myColDef2 As New ColumnDefinition 
myColDef2.Width = New GridLength(lj GridUnitType.Star) 

Dim myColDefB As New ColumnDefinition 
myColDefB.Width = New GridLength(l, GridUnitType.Auto) 

'Add the ColumnDefinitions to the Grid 
myGrid.ColumnDefinitions.Add(myColDefl) 
myGrid.ColumnDefinitions.Add(myColDef2) 
myGrid.ColumnDefinitions.Add(myColDef3) 

'Add the first child StackPanel. 

Dim myStackPanel As New StackPanel 

myStackPanel.HorizontalAlignment = System.Windows.HorizontalAlignment.Left 
myStackPanel.VerticalAlignment = System.Windows.VerticalAlignment.Top 
Grid.SetColumn(myStackPanelj 0) 

Grid.SetRow(myStackPanel, 0) 

Dim myTextBlockl As New TextBlock 
myTextBlockl.FontSize = 18 

myT extBlockl.HorizontalAlignment = System.Windows.HorizontalAlignment.Center 
myTextBlockl.Margin = New Thickness(0j 0, 0, 15) 
myTextBlockl.Text = "StackPanel 1" 

Dim myButtonl As New Button 

myButtonl.Margin = New Thickness(0^ 10^ 0, 10) 
myButtonl.Content = "Button 1" 

Dim myButton2 As New Button 

myButtonl.Margin = New Thickness(0j 10^ 0, 10) 
myButtonl.Content = "Button 2" 

Dim myButtonB As New Button 

myButtonB.Margin = New Thickness(0j 10^ 0, 10) 

Dim myTextBlockl As New TextBlock 

myTextBlockl.Text = "ColumnDefinition.Width = ""Auto""" 

Dim myTextBlockB As New TextBlock 

myTextBlockB.Text = "StackPanel.HorizontalAlignment = ""Left""" 

Dim myTextBlockA As New TextBlock 

myTextBlockA.Text = "StackPanel.VerticalAlignment = ""Top""" 

Dim myTextBlockS As New TextBlock 

myTextBlockS.Text = "StackPanel.Orientation = ""Vertical""" 

Dim myTextBlocke As New TextBlock 
myTextBlockB.Text = "Button.Margin = ""1,10,0,10""" 
myStackPanel.Children.Add(myTextBlockl) 
myStackPanel.Children.Add(myButtonl) 
myStackPanel.Children.Add(myButton!) 
myStackPanel.Children.Add(myButtons) 
myStackPanel.Children.Add(myTextBlockl) 
myStackPanel.Children.Add(myTextBlocks) 
myStackPanel.Children.Add(myTextBlock4) 
myStackPanel.Children.Add(myTextBlocks) 
myStackPanel.Children.Add(myTextBlocke) 

'Add the second child StackPanel. 

Dim myStackPanel! As New StackPanel 

myStackPanel!.HorizontalAlignment = System.Windows.HorizontalAlignment.Stretch 






myStackPanel2.\/erticalAlignment = System.Windows.VerticalAlignment.Top 
myStackPanel2.Orientation = Orientation.Vertical 
Grid.SetColumn(myStackPanel2j 1) 

Grid.SetRow(myStackPanel2j 0) 

Dim myTextBlock? As New TextBlock 
myTextBlock?.FontSize = 18 

myTextBlock7.HorizontalAlignment = System.Windows .FIorizontalAlignment .Center 
myTextBlock?.Margin = New Thickness(0j 0^ 0, 15) 
myTextBlock7.Text = "StackPanel 2" 

Dim myButtonA As New Button 

myButtonA.Margin = New Thickness(10j 0j 10j 0) 
myButtonA.Content = "Button 4" 

Dim myButtonB As New Button 

myButtonB.Margin = New Thickness(10j 0j 10j 0) 
myButtonB.Content = "Button 5" 

Dim myButtonS As New Button 

myButtonS.Margin = New Thickness(10j 0j 10, 0) 
myButtonS.Content = "Button 6" 

Dim myTextBlockS As New TextBlock 

myTextBlockS.HorizontalAlignment = System.Windows.FIorizontalAlignment.Center 
myTextBlockS.Text = "ColumnDefinition.Width = 

Dim myTextBlockS As New TextBlock 

myTextBlockS. FIorizontalAlignment = System. Windows. FIorizontalAlignment. Center 
myTextBlockS.Text = "StackPanel. FIorizontalAlignment = ""Stretch""" 

Dim myTextBlockl0 As New TextBlock 

myTextBlockl0.FIorizontalAlignment = System.Windows .FIorizontalAlignment .Center 
myTextBlockl0.Text = "StackPanel.VerticalAlignment = ""Top""" 

Dim myTextBlockll As New TextBlock 

myTextBlockll. FIorizontalAlignment = System. Windows. FIorizontalAlignment. Center 
myTextBlockll. Text = "StackPanel. Orientation = ""Florizontal""" 

Dim myTextBlockll As New TextBlock 

myTextBlockll.FIorizontalAlignment = System. Windows .FIorizontalAlignment .Center 

myTextBlockll.Text = "Button.Margin = ""10,0,10,0""" 

myStackPanell.Children.Add(myTextBlock!) 

myStackPanell.Children.Add(myButtonA) 

myStackPanell.Children.Add(myButtons) 

myStackPanell.Children.Add(myButtons) 

myStackPanell.Children.Add(myTextBlockS) 

myStackPanell.Children.Add(myTextBlockS) 

myStackPanell.Children.Add(myTextBlockl0) 

myStackPanell.Children.Add(myTextBlockll) 

myStackPanell.Children.Add(myTextBlockll) 

'Add the final child StackPanel. 

Dim myStackPanelB As New StackPanel 

myStackPanelB.FIorizontalAlignment = System.Windows .FIorizontalAlignment. Left 
myStackPanelB.VerticalAlignment = System.Windows.VerticalAlignment.Top 
Grid.SetColumn(myStackPanel3, 2) 

Grid.SetRow(myStackPanel3, 0) 

Dim myTextBlockl3 As New TextBlock 
myTextBlockl3.FontSize = 18 

myTextBlockl3.FIorizontalAlignment = System. Windows .FIorizontalAlignment .Center 
myTextBlockl3.Margin = New Thickness(0, 0, 0, 15) 
myTextBlockl3.Text = "StackPanel 3" 

Dim myButton! As New Button 
myButtonl.Margin = New Thickness(10) 
myButtonl.Content = "Button 7" 

Dim myButtonS As New Button 
myButtonS.Margin = New Thickness(10) 
myButtonS.Content = "Button 8" 

Dim myButtonS As New Button 
myButtonS.Margin = New Thickness(10) 
myButtonS.Content = "Button S" 

Dim myTextBlocklA As New TextBlock 

myTextBlocklA.Text = "ColumnDefinition.Width = ""Auto""" 

Dim myTextBlockl5 As New TextBlock 

myTextBlockl5.Text = "StackPanel. FIorizontalAlignment = ""Left""" 

Dim mvTextBlocklS As New TextBlock 









myTextBlocklS.Text = "StackPanel.VenticalAlignment = ""Top 
Dim myTextBlockl? As New TextBlock 

myTextBlockl7.Text = "StackPanel.Orientation = ""Vertical" 
Dim myTextBlocklB As New TextBlock 
myTextBlocklS.Text = "Button.Margin = "" 10 """ 
myStackPanelB.Children.Add(myTextBlocklB) 
myStackPanelB.Children.Add(myButton?) 
myStackPanelB.Children.Add(myButtons) 
myStackPanelB.Children.Add(myButton9) 
myStackPanelB.Children.Add(myTextBlockl4) 
myStackPanelB.Children.Add(myTextBlocklB) 
myStackPanelB.Children.Add(myTextBlocklB) 
myStackPanelB.Children.Add(myTextBlockl?) 
myStackPanelB.Children.Add(myTextBlocklS) 

'Add child content to the parent Grid. 
myGrid.Children.Add(myStackPanel) 
myGrid.Children.Add(myStackPanel2) 
myGrid.Children.Add(myStackPanelB) 

'Add the Grid as the lone child of the Border. 
myBorder.Child = myGrid 





<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" WindowTitle="MarginSj Padding and 
Alignment Sample"> 

<Border Background="LightBlue" 

BorderBrush="Black" 

BorderThickness="2" 

CornerRadius="45" 

Padding="25"> 

<Grid Background="White" ShowGridLines="True"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="Auto"/> 

<ColumnDefinition Width="*"/> 
cColumnDefinition Width="Auto"/> 

</Grid.ColumnDefinitions> 

cStackPanel Grid.Column="0" Grid.Row="0" HorizontalAlignment="Left" Name="StackPanell" 

VerticalAlignment="Top"> 

<TextBlock FontSize="18" HorizontalAlignment="Center" Margin="0,0,0,15">StackPanell</TextBlock> 
<Button Margin="0,10,0,10">Button l</Button> 

<Button Margin="0,10,0,10">Button 2</Button> 

<Button Margin="0,10,0,10">Button 3</Button> 

<TextBlock>ColumnDefinition.Width="Auto"</TextBlock> 
<TextBlock>StackPanel.HorizontalAlignment="Left"</TextBlock> 

<TextBlock>StackPanel.VerticalAlignment="Top"</TextBlock> 
<TextBlock>StackPanel.Orientation="Vertical"</TextBlock> 

<TextBlock>Button.Margin="0,10,0,10"</TextBlock> 

</StackPanel> 

<StackPanel Grid.Column="l" Grid.Row="0" HorizontalAlignment="Stretch" Name="StackPanel2" 

VerticalAlignment="Top" Orientation="Vertical"> 

<TextBlock FontSize="18" HorizontalAlignment="Center" Margin="0,0,0,15">StackPanel2</TextBlock> 
<Button Margin="10,0,10,0">Button 4</Button> 

<Button Margin="10,0,10,0">Button 5</Button> 

<Button Margin="10,0,10,0">Button 6</Button> 

<TextBlock HorizontalAlignment="Center">ColumnDefinition.Width="*"</TextBlock> 

<TextBlock HorizontalAlignment="Center">StackPanel.HorizontalAlignment="Stretch"</TextBlock> 
cTextBlock HorizontalAlignment="Center">StackPanel.VerticalAlignment="Top"</TextBlock> 
cTextBlock HorizontalAlignment="Center">StackPanel.Orientation="Horizontal"</TextBlock> 

<TextBlock HorizontalAlignment="Center">Button.Margin="10,0,10,0"</TextBlock> 

</StackPanel> 

<StackPanel Grid.Column="2" Grid.Row="0" HorizontalAlignment="Left" Name="StackPanel3" 

VerticalAlignment="Top"> 

<TextBlock FontSize="18" HorizontalAlignment="Center" Margin="0,0,0,15">StackPanel3</TextBlock> 
<Button Margin="10">Button 7</Button> 

<Button Margin="10">Button 8</Button> 

<Button Margin="10">Button 9</Button> 

<TextBlock>ColumnDefinition.Width="Auto"</TextBlock> 
<TextBlock>StackPanel.HorizontalAlignment="Left"</TextBlock> 

<TextBlock>StackPanel.VerticalAlignment="Top"</TextBlock> 
<TextBlock>StackPanel.Orientation="Vertical"</TextBlock> 

<TextBlock>Button.Margin="10"</TextBlock> 

</StackPanel> 

</Grid> 

</Border> 

</Page> 


When compiled, the preceding application yields a Ul that looks like the following illustration. The effects of the 
various property values are evident in the spacing between elements, and significant property values for elements 
in each column are shown within TextBlock elements. 




What's Next 

Positioning properties defined by the FrameworkElement class enable fine control of element placement within 
WPF applications. You now have several techniques you can use to better position elements using WPF. 

Additional resources are available that explain WPF layout in greater detail. The Panels Overview topic contains 
more detail about the various Panel elements. The topic Walkthrough: My first WPF desktop application introduces 
advanced techniques that use layout elements to position components and bind their actions to data sources. 

See also 

• FrameworkElement 

• HorizontalAlignment 

• VerticalAlignment 

• Margin 

• Panels Overview 

• Layout 

• WPF Layout Gallery Sample 
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The topics in this section describe how to use the four WPF base elements: UlElement, ContentElement, 
FrameworkElement, and FrameworkContentElement. 

In This Section 

Make a UlElement Transparent or Semi-Transparent 

Animate the Size of a FrameworkElement 

Determine Whether a Freezable Is Frozen 

Handle a Loaded Event 

Set Margins of Elements and Controls 

Make a Freezable Read-Only 

Obtain a Writable Copy of a Read-Only Freezable 

Flip a UlElement Horizontally or Vertically 

Use a ThicknessConverter Object 

Handle the ContextMenuOpening Event 

Reference 

UlElement 

ContentElement 

FrameworkElement 

FrameworkContentElement 

Related Sections 


Base Elements 




How to; Make a UlElement Transparent or Semi- 
Transparent 
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This example shows how to make a UlElement transparent or semi-transparent To make an element transparent or 
semi-transparent you set its Opacity property. A value of 0.0 makes the element completely transparent while a 
value of 1.0 makes the element completely opaque. A value of 0.5 makes the element 50% opaque, and so on. 
An element's Opacity is set to 1.0 by default 

Example 

The following example sets the Opacity of a button to 0.25 , making it and its contents (in this case, the button's 
text) 25% opaque. 

<!-- Both the button and its text are made 25% opaque. --> 

<Button Opacity="0.25">A Button</Button> 


// 

// Both the button and its text are made 25% opaque. 

// 

Button myTwentyFivePercentOpaqueButton = new Button(); 
myTwentyFivePercentOpaqueButton.Opacity = new Double()j 
myTwentyFivePercentOpaqueButton.Opacity = 0.25j 
myTwentyFivePercentOpaqueButton.Content = "A Button"; 


If an element's contents have their own Opacity settings, those values are multiplied against the containing 
elements Opacity. 

The following example sets a button's Opacity to 0.25 , and the Opacity of an Image control contained with in the 
button to 0.5 . As a result, the image appears 12.5% opaque: 0.25 * 0.5 = 0.125. 

<!-- The image contained within this button has an effective 
opacity of 0.125 (0.25 * 0.5 = 0.125). --> 

<Button Opacity="0.25"> 

<StackPanel Orientation="Horizontal"> 

cTextBlock VerticalAlignment="Center" Margin="10">A Button</TextBlock> 

<Image Source="sampleImages\berries.jpg" Width="50" Height="50" 

Opacity="0.5"/> 

</StackPanel> 

</Button> 












// 

// The image contained within this button has an 
// effective opacity of 0.125 (0.25*0.5 = 0.125)j 
// 

Button mylmageButton = new Button(); 
mylmageButton.Opacity = new Double(); 
mylmageButton.Opacity = 0.25; 

StackPanel mylmageStackPanel = new StackPanel(); 
mylmageStackPanel.Orientation = Orientation.Horizontal; 

TextBlock myTextBlock = new TextBlock(); 
myTextBlock.VerticalAlignment = VerticalAlignment.Center; 
myTextBlock.Margin = new Thickness(10); 
myTextBlock.Text = "A Button"; 
mylmageStackPanel.Children.Add(myTextBlock); 

Image mylmage = new Image(); 

Bitmapimage myBitmapImage = new Bitmaplmage(); 
myBitmapImage.Beginlnlt(); 

myBitmapImage.UriSource = new Llri("sampleImages/berries.jpg"jLlriKind.Relative); 
myBitmapImage.Endinit(); 
mylmage.Source = myBitmapImage; 

ImageBrush mylmageBrush = new ImageBrush(myBitmapImage); 

mylmage.Width = 50; 

mylmage.Height = 50; 

mylmage.Opacity = 0.5; 

mylmageStackPanel.Children.Add(myImage); 

mylmageButton.Content = mylmageStackPanel; 


Another way to control the opacity of an element is to set the opacity of the Brush that paints the element. This 
approach enables you to selectively alter the opacity of portions of an element, and provides performance benefits 
over using the element's Opacity property. The following example sets the Opacity of a SolidColorBrush used to 
paint the button's Background is set to 0.25 . As a result, the brush's background is 25% opaque, but its contents 
(the button's text) remain 100% opaque. 

<!-- This button's background is made 25% opaquej but its 
text remains 100% opaque. --> 

<Button> 

<Button.Background> 

<SolidColorBrush Color="Gray" Opacity="0.25" /> 

</Button.Backgrounds 
A Button 
</Button> 


// 

// This button's background is made 25% opaque, 

// but its text remains 100% opaque. 

// 

Button myOpaqueTextButton = new Button(); 

SolidColorBrush mySolidColorBrush = new SolidColorBrush(Colors.Gray); 
mySolidColorBrush.Opacity = 0.25; 
myOpaqueTextButton.Background = mySolidColorBrush; 
myOpaqueTextButton.Content = "A Button"; 


You may also control the opacity of individual colors within a brush. For more information about colors and 
brushes, see Painting with Solid Colors and Gradients Overview. For an example showing how to animate an 
element's opacity, see Animate the Opacity of an Element or Brush. 




How to: Animate the Size of a FrameworkElement 
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To animate the size of a FrameworkElement, you can either animate its Width and Height properties or use an 
animated ScaleTransform. 

In the following example animates the size of two buttons using these two approaches. One button is resized by 
animating its Width property and another is resized by animating a ScaleTransform applied to its RenderTransform 
property. Each button contains some text. Initially, the text appears the same in both buttons, but as the buttons are 
resized, the text in the second button becomes distorted. 

Example 




<!- - AnimatingSizeExample.xaml 

This example shows two ways of animating the size 
of a framework element. --> 

<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="Microsoft.Samples.Animation.AnimatingSizeExample" 
WindowTitle="Animatlng Size Example"> 

<Canvas Width="650" Height="400"> 

<Button Name="AnimatedWidthButton" 

Canvas.Left="20" Canvas.Top="20" 

Width="200" Height="150" 

BorderBrush="Red" BorderThickness="5"> 

Click Me 

<Button.Triggers> 

<!-- Animate the button's Width property. --> 

<EventTrigger RoutedEvent="Button.Loaded"> 

<BeginStoryboard) 

<Storyboard> 

<DoubleAnimation 

Storyboard.TargetName="AnimatedWidthButton" 

Storyboard.Ta rgetProperty="(Button.Width)" 

To="500" Duration="0:0:10" AutoReverse="True" 
RepeatBehavior="Forever" /> 

</Storyboard> 

</BeginStoryboard) 

</EventTrigger) 

</Button.Triggers) 

</Button) 

<Button 

Canvas.Left="20" Canvas.Top="200" 

Width="200" Height="150" 

BorderBrush="Black" BorderThickness="3") 

Click Me 

<Button.RenderTransform) 

<ScaleTransform x:Mame="MyAnimatedScaleTransform" 
ScaleX="l" ScaleY="l" /) 

</Button.RenderTransform) 

<Button.Triggers) 

<!-- Animate the ScaleX property of a ScaleTransform 
applied to the button. --) 

<EventTrigger RoutedEvent="Button.Loaded") 

<BeginStoryboard) 

<Storyboard) 

<DoubleAnimation 

Storyboard.TargetName="MyAnimatedScaleTransform" 
Storyboard.TargetProperty="(ScaleTransform.ScaleX)" 
To="3.0" Duration="0:0:10" AutoReverse="True" 
RepeatBehavior="Forever" /) 

</Storyboard) 

</BeginStoryboard) 

</EventTrigger) 

</Button.Triggers) 

</Button) 

</Canvas) 

</Page) 


When you transform an element, the entire element and its contents are transformed. When you directly alter the 
size of an element, as in the case of the first button, the element's contents are not resized unless their size and 
position depend on the size of their parent element. 

Animating the size of an element by applying an animated transform to its RenderTransform property provides 



better performance than animated its Width and Height directly, because the RenderTransform property does not 
trigger a layout pass. 

For more information about animating properties, see the Animation Overview. For more information about 
transforms, see the Transforms Overview. 


How to: Determine Whether a Freezable Is Frozen 
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This example shows how to determine whether a Freezable object is frozen. If you try to modify a frozen Freezable 
object, it throws an InvalidOperationException. To avoid throwing this exception, use the IsFrozen property of the 
Freezable object to determine whether it is frozen. 

Example 

The following example freezes a SolidColorBrush and then tests it by using the IsFrozen property to determine 
whether it is frozen. 


Button myButton = new Button(); 

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow); 

if (myBrush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
my Brush. FreezeO; 

} 

myButton.Background = myBrush; 

if (myBrush.IsFrozen) // Evaluates to true. 

{ 

// If the brush is frozen^ create a clone and 
// modify the clone. 

SolidColorBrush myBrushClone = myBrush.Clone(); 
myBrushClone.Color = Colors.Red; 
myButton.Background = myBrushClone; 

} 

else 

{ 

// If the brush is not frozen^ 

// it can be modified directly. 
myBrush.Color = Colors.Red; 

} 





Dim myButton As New Button() 

Dim myBnush As New SolidColorBrush(Colons.Yellow) 

If myBnush.CanFneeze Then 

' Makes the brush unmodifiable. 
myBnush.FneezeO 
End If 

myButton.Background = myBnush 

If myBnush.IsFrozen Then ' Evaluates to true. 

' If the brush is frozen^ create a clone and 
' modify the clone. 

Dim myBrushClone As SolidColorBrush = myBrush.Clone() 
myBrushClone.Color = Colors.Red 
myButton.Background = myBrushClone 

Else 

' If the brush is not frozen, 

' it can be modified directly. 
myBnush.Color = Colors.Red 
End If 


For more information about Freezable objects, see the Freezable Objects Overview. 

See also 

• Freezable 

• IsFrozen 

• Freezable Objects Overview 

• Flow-to Topics 
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This example shows how to handle the FrameworkElement.Loaded event, and an appropriate scenario for handling 
that event. The handler creates a Button when the page loads. 

Example 

The following example uses Extensible Application Markup Language (XAML) together with a code-behind file. 

<Stacl<Panel 

xmlns="http://schemas.mlcnosoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml" 
x:Class="SDKSample.FELoaded" 

Loaded="OnLoad" 

Name="root" 

> 

</StackPanel> 


void OnLoad(object sendeCj RoutedEventAngs e) 

{ 

Button bl = new Button(); 
bl.Content = "New Button"; 
root.Children.Add(bl); 
bl.Height = 25; 
bl.Width = 200; 

bl.HorizontalAlignment = HorizontalAlignment.Left; 

} 


Private Sub OnLoad(ByVal sender As Objectj ByVal e As RoutedEventArgs) 
Dim bl As Button = New Button() 
bl.Content = "New Button" 
root.Children.Add(bl) 
bl.Height = 25 
bl.Width = 200 

bl.HorizontalAlignment = HorizontalAlignment.Left 
End Sub 


See also 

• FrameworkElement 

• Object Lifetime Events 

• Routed Events Overview 

• How-to Topics 
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This example describes how to set the Margin property, by changing any existing property value for the margin in 
code-behind. The Margin property is a property of the FrameworkElement base element, and is thus inherited by a 
variety of controls and other elements. 

This example is written in Extensible Application Markup Language (XAML), with a code-behind file that the XAML 
refers to. The code-behind is shown in both a C# and a Microsoft Visual Basic version. 

Example 

<Button Click="OnClicl<" Margin="10" Name="btnl"> 

Click To See Change!!</Button> 


void OnClick(object sender, RoutedEventArgs e) 

{ 

// Get the current value of the property. 

Thickness marginThickness = btnl.Margin; 

// If the current leftlength value of margin is set to 10 then change it to a new value. 
// Otherwise change it back to 10. 
if(marginThickness.Left == 10) 

{ 

btnl.Margin = new Thickness(60); 

} else { 

btnl.Margin = new Thickness(10); 

} 

} 


Private Sub OnClick(ByVal sender As Object, ByVal e As RoutedEventArgs) 

' Get the current value of the property. 

Dim marginThickness As Thickness 
marginThickness = btnl.Margin 

' If the current leftlength value of margin is set to 10 then change it to a new value. 
' Otherwise change it back to 10. 

If marginThickness.Left = 10 Then 
btnl.Margin = New Thickness(60) 

Else 

btnl.Margin = New Thickness(10) 

End If 
End Sub 





How to: Make a Freezable Read-Only 
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This example shows how to make a Freezable read-only by calling its Freeze method. 

You cannot freeze a Freezable object if any one of the following conditions is true about the object: 

• It has animated or data bound properties. 

• It has properties that are set by a dynamic resource. For more information about dynamic resources, see the 
XAML Resources. 

• It contains Freezable sub-objects that cannot be frozen. 

If these conditions are false for your Freezable object and you do not intend to modify it, consider freezing it to 
gain performance benefits. 

Example 

The following example freezes a SolidColorBrush, which is a type of Freezable object. 

Button myButton = new Button(); 

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow)j 

if (myBrush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
my Brush. FreezeO; 

} 

myButton.Background = myBrush; 

Dim myButton As New Button() 

Dim myBrush As New SolidColorBrush(Colors.Yellow) 

If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.Freeze() 

End If 

myButton.Background = myBrush 

For more information about Freezable objects, see the Freezable Objects Overview. 

See also 

• Freezable 

• CanFreeze 

• Freeze 

• Freezable Objects Overview 

• How-to Topics 
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This example shows how to use the Clone method to create a writable copy of a read-only Freezable. 

After a Freezable object is marked as read-only ("frozen"), you cannot modify it. However, you can use the Clone 
method to create a modifiable clone of the frozen object. 

Example 

The following example creates a modifiable clone of a frozen SolidColorBrush object. 


Button myButton = new Button(); 

SolidColorBrush myBrush = new SolidColorBrush(Colors.Yellow)j 

// Freezing a Freezable before it provides 
// performance improvements if you don't 
// intend on modifying it. 
if (myBrush.CanFreeze) 

{ 

// Makes the brush unmodifiable. 
my Brush. FreezeO; 

} 

myButton.Background = myBrush; 

// If you need to modify a frozen brush, 

// the Clone method can be used to 
// create a modifiable copy. 

SolidColorBrush myBrushClone = myBrush.Clone()j 

// Changing myBrushClone does not change 
// the color of myButton, because its 
// background is still set by myBrush. 
myBrushClone.Color = Colors.Red; 

// Replacing myBrush with myBrushClone 
// makes the button change to red. 
myButton.Background = myBrushClone; 





Dim myButton As New Button() 

Dim myBnush As New SolidColorBrush(Colons.Yellow) 

' Freezing a Freezable before it provides 
' performance improvements if you don't 
' intend on modifying it. 

If myBrush.CanFreeze Then 

' Makes the brush unmodifiable. 
myBrush.FreezeO 
End If 


myButton.Background = myBrush 

' If you need to modify a frozen brush, 

' the Clone method can be used to 
' create a modifiable copy. 

Dim myBrushClone As SolidColorBrush = myBrush.Clone() 

' Changing myBrushClone does not change 
' the color of myButton, because its 
' background is still set by myBrush. 
myBrushClone.Color = Colors.Red 

' Replacing myBrush with myBrushClone 
' makes the button change to red. 
myButton.Background = myBrushClone 


For more information about Freezable objects, see the Freezable Objects Overview. 

See also 

• Freezable 

• CloneCurrentValue 

• Freezable Objects Overview 

• Flow-to Topics 
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This example shows how to use a ScaleTransform to flip a UlElement horizontally or vertically. In this example, a 
Button control (a type of UlElement) is flipped by applying a ScaleTransform to its RenderTransform property. 

Example 

The following illustration shows the button to flip. 



The following shows the code that creates the button. 

<Button Content="Flip me!" Padding="5"> 

</Button> 


Example 

To flip the button horizontally, create a ScaleTransform and set its ScaleX property to -1. Apply the ScaleTransform 
to the button's RenderTransform property. 

<Button Content="Flip me!" Padding="5"> 

<Button.RendenTransfonmx 

<ScaleTr'ansform ScaleX="-l" /> 

</Button.RenderTransform> 

</Button> 



The button after applying the ScaleTransform 

Example 

As you can see from the previous illustration, the button was flipped, but it was also moved. That's because the 
button was flipped from its top left corner. To flip the button in place, you want to apply the ScaleTransform to its 
center, not its corner. An easy way to apply the ScaleTransform to the buttons center is to set the button's 
RenderTransformOrigin property to 0.5, 0.5. 




















<Button Content="Flip me!" Padding="5" 
Render'Transfor'mOrigin="0.5j0.5"> 
<Button. Render'Tr'ansfor'm> 

<ScaleTr'ansfor'm ScaleX="-l" /> 

</Button.RenderTransform> 

</Button> 



The button with a RenderTransformOrigin of 0.5, 0.5 

Example 

To flip the button vertically, set the ScaleTransform object's ScaleY property instead of its ScaleX property. 

<Button Content="Flip me!" Padding="5" 

RendenTnansfonmOrigin="0.5,0.5"> 

<Button.RendenTnansfonm> 

<ScaleTnansform ScaleY="-l" /> 

</Button.RenderTransform> 

</Button> 



The vertically flipped button 

See also 


• Transforms Overview 
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Example 

This example shows how to create an instance of ThicknessConverter and use it to change the thickness of a 
border. 

The example defines a custom method called changethickness ; this method first converts the contents of a 
ListBoxItem, as defined in a separate Extensible Application Markup Language (XAML) file, to an instance of 
Thickness, and later converts the content into a String. This method passes the ListBoxItem to a ThicknessConverter 
object, which converts the Content of a ListBoxItem to an instance of Thickness. This value is then passed back as 
the value of the BorderThickness property of the Border. 

This example does not run. 

private void changeThickness(object sender, SelectionChangedEventArgs args) 

{ 

ListBoxItem li = ((sender as ListBox).Selecteditem as ListBoxItem); 

ThicknessConverter mylhicknessConverter = new ThicknessConverter()j 

Thickness thl = (Thickness)myThicknessConverter.ConvertFromString(li.Content.ToStringO); 
horderl.BorderThickness = thl; 

hlhickness.Text = "Border.BorderThickness =" + li.Content.ToStringO; 

} 


Private Suh changeThickness(ByVal sender As Object, ByVal args As SelectionChangedEventArgs) 

Dim li As ListBoxItem = CType(CType(sender, ListBox).Selecteditem, ListBoxItem) 

Dim mylhicknessConverter As System.Windows.ThicknessConverter = New System.Windows.ThicknessConverter() 
Dim thl As Thickness = CType(myThicknessConverter.ConvertFromString(li.Content.ToStringO), Thickness) 
horderl.BorderThickness = thl 

bThickness.Text = "Border.BorderThickness =" + li.Content.ToStringO 
End Sub 


See also 

• Thickness 

• ThicknessConverter 

• Border 

• How to: Change the Margin Property 

• How to: Convert a ListBoxItem to a new Data Type 

• Panels Overview 
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The ContextMenuOpening event can be handled in an application to either adjust an existing context menu prior to 
display or to suppress the menu that would otherwise be displayed by setting the Handled property to true in the 
event data. The typical reason for setting Handled to true in the event data is to replace the menu entirely with a 
new ContextMenu object, which sometimes requires canceling the operation and starting a new open. If you write 
handlers for the ContextMenuOpening event, you should be aware of timing issues between a ContextMenu 
control and the service that is responsible for opening and positioning context menus for controls in general. This 
topic illustrates some of the code techniques for various context menu opening scenarios and illustrates a case 
where the timing issue comes into play. 

There are several scenarios for handling the ContextMenuOpening event: 

• Adjusting the menu items before display. 

• Replacing the entire menu before display. 

• Completely suppressing any existing context menu and displaying no context menu. 

Example 

Adjusting the Menu Items Before Display 

Adjusting the existing menu items is fairly simple and is probably the most common scenario. You might do this in 
order to add or subtract context menu options in response to current state information in your application or 
particular state information that is available as a property on the object where the context menu is requested. 

The general technique is to get the source of the event, which is the specific control that was right-clicked, and get 
the ContextMenu property from it. You typically want to check the Items collection to see what context menu items 
already exist in the menu, and then add or remove appropriate new Menultem items to or from the collection. 

void AddItemToCM(object sender, ContextMenuEventArgs e) 

{ 

//check if Item4 is already there, this will prohahly run more than once 
FrameworkElement fe = e.Source as FrameworkElement; 

ContextMenu cm = fe.ContextMenu; 
foreach (Menultem mi in cm.Items) 

{ 

if ((String)mi.Header == "Item4") return; 

} 

Menultem mi4 = new Menultem(); 
mi4.Header = "Item4"; 
fe.ContextMenu.Items.Add(mi4); 

} 


Replacing the Entire Menu Before Display 

An alternative scenario is if you want to replace the entire context menu. You could of course also use a variation of 
the preceding code, to remove every item of an existing context menu and add new ones starting with item zero. 
But the more intuitive approach for replacing all items in the context menu is to create a new ContextMenu, 
populate it with items, and then set the FrameworkElement.ContextMenu property of a control to be the new 
ContextMenu. 







The following is the simple handler code for replacing a ContextMenu. The code references a custom BuiidMenu 
method, which is separated out because it is called by more than one of the example handlers. 

void Handler'ForCMO(object sender, ContextMenuEventArgs e) 

{ 

FrameworkElement fe = e.Source as FrameworkElement; 
fe.ContextMenu = BuildMenu(); 

} 


ContextMenu BuildMenu() 

{ 

ContextMenu theMenu = new ContextMenu(); 
Menultem mia = new Menultem(); 
mia.Header = "Iteml"; 

Menultem mib = new Menultem(); 
mlb.Header = "Item2"; 

Menultem mic = new Menultem(); 
mic.Header = "ItemB"; 
theMenu.Items.Add(mia); 
theMenu.Items.Add(mib); 
theMenu.Items.Add(mic); 
return theMenu; 

} 


However, if you use this style of handler for ContextMenuOpening, you can potentially expose a timing issue if the 
object where you are setting the ContextMenu does not have a preexisting context menu. When a user right-clicks a 
control, ContextMenuOpening is raised even if the existing ContextMenu is empty or null. But in this case, whatever 
new ContextMenu you set on the source element arrives too late to be displayed. Also, if the user happens to right- 
click a second time, this time your new ContextMenu appears, the value is non null, and your handler will properly 
replace and display the menu when the handler runs a second time. This suggests two possible workarounds: 

1. Insure that ContextMenuOpening handlers always run against controls that have at least a placeholder 
ContextMenu available, which you intend to be replaced by the handler code. In this case, you can still use 
the handler shown in the previous example, but you typically want to assign a placeholder ContextMenu in 
the initial markup: 

<StackPanel> 

<Rectangle Fill="Yellow" Width="200" Height="100" ContextMenuOpening="HandlenForCMO"> 

<Rectangle.ContextMenu> 

<ContextMenu> 

<MenuItem>Initial menu; this will be replaced ...</MenuItem> 

</ContextMenu> 

</Rectangle.ContextMenu> 

</Rectangle> 

<TextBlock>Right-click the rectangle above, context menu gets replaced</TextBlock> 

</StackPanel> 


2. Assume that the initial ContextMenu value might be null, based on some preliminary logic. You could either 
check ContextMenu for null, or use a flag in your code to check whether your handler has been run at least 
once. Because you assume that the ContextMenu is about to be displayed, your handler then sets Handled to 
true in the event data. To the ContextMenuService that is responsible for context menu display, a true 
value for Handled in the event data represents a request to cancel the display for the context menu / control 
combination that raised the event. 

Now that you have suppressed the potentially suspect context menu, the next step is to supply a new one, then 
display it. Setting the new one is basically the same as the previous handler: you build a new ContextMenu and set 
the control source's FrameworkElement.ContextMenu property with it. The additional step is that you must now 







force the display of the context menu, because you suppressed the first attempt. To force the display, you set the 
Popup.lsOpen property to true within the handler. Be careful when you do this, because opening the context 
menu in the handler raises the ContextMenuOpening event again. If you reenter your handler, it becomes infinitely 
recursive. This is why you always need to check for null or use a flag if you open a context menu from within a 
ContextMenuOpening event handler. 

Suppressing Any Existing Context Menu and Displaying No Context 
Menu 

The final scenario, writing a handler that suppresses a menu totally, is uncommon. If a given control is not 
supposed to display a context menu, there are probably more appropriate ways to assure this than by suppressing 
the menu just when a user requests it. But if you want to use the handler to suppress a context menu and show 
nothing, then your handler should simply set Handled to true in the event data. The ContextMenuService that is 
responsible for displaying a context menu will check the event data of the event it raised on the control. If the event 
was marked Handled anywhere along the route, then the context menu open action that initiated the event is 
suppressed. 

void HandlerForCM02(object sendeCj ContextMenuEventArgs e) 

{ 

if (!FlagForCustomContextMenu) 

{ 

e.Handled = true; //need to suppress empty menu 
FrameworkElement fe = e.Source as FrameworkElement; 
fe.ContextMenu = BuildMenu(); 

FlagForCustomContextMenu = true; 
fe.ContextMenu.IsOpen = true; 

} 

} 

} 


See also 

• ContextMenu 

• FrameworkElement.ContextMenu 

• Base Elements Overview 

• ContextMenu Overview 
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WPF programming elements often exist in some form of tree relationship to each other. For instance, an 
application Ul created in XAML can be conceptualized as an object tree. The element tree can be further divided 
into two discrete yet sometimes parallel trees: the logical tree and the visual tree. Serialization in WPF involves 
saving the state of these two trees as well as application state and writing it to a file, potentially as XAML. 
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In many technologies, elements and components are organized in a tree structure where developers directly 
manipulate the object nodes in the tree to affect the rendering or behavior of an application. Windows 
Presentation Foundation (WPF) also uses several tree structure metaphors to define relationships between 
program elements. For the most part WPF developers can create an application in code or define portions of the 
application in XAML while thinking conceptually about the object tree metaphor, but will be calling specific API or 
using specific markup to do so rather than some general object tree manipulation API such as you might use in 
XML DOM. WPF exposes two helper classes that provide a tree metaphor view, LogicalTreeHelper and 
VisualTreeHelper. The terms visual tree and logical tree are also used in the WPF documentation because these 
same trees are useful for understanding the behavior of certain key WPF features. This topic defines what the 
visual tree and logical tree represent, discusses how such trees relate to an overall object tree concept, and 
introduces LogicalTreeHelper and VisualTreeHelpers. 

Trees in WPF 

The most complete tree structure in WPF is the object tree. If you define an application page in XAML and then 
load the XAML, the tree structure is created based on the nesting relationships of the elements in the markup. If 
you define an application or a portion of the application in code, then the tree structure is created based on how 
you assign property values for properties that implement the content model for a given object. In Windows 
Presentation Foundation (WPF), there are two ways that the complete object tree is conceptualized and can be 
reported to its public API: as the logical tree and as the visual tree. The distinctions between logical tree and visual 
tree are not always necessarily important, but they can occasionally cause issues with certain WPF subsystems 
and affect choices you make in markup or code. 

Even though you do not always manipulate either the logical tree or the visual tree directly, understanding the 
concepts of how the trees interact is useful for understanding WPF as a technology. Thinking of WPF as a tree 
metaphor of some kind is also crucial to understanding how property inheritance and event routing work in WPF. 


NOTE 

Because the object tree is more of a concept than an actual API, another way to think of the concept is as an object graph. 
In practice, there are relationships between objects at run time where the tree metaphor will break down. Nevertheless, 
particularly with XAML-defined Ul, the tree metaphor is relevant enough that most WPF documentation will use the term 
object tree when referencing this general concept. 


The Logical Tree 

In WPF, you add content to Ul elements by setting properties of the objects that back those elements. For 
example, you add items to a ListBox control by manipulating its Items property. By doing this, you are placing 
items into the ItemCollection that is the Items property value. Similarly, to add objects to a DockPanel, you 
manipulate its Children property value. Here, you are adding objects to the UlElementCollection. For a code 
example, see How to: Add an Element Dynamically. 

In Extensible Application Markup Language (XAML), when you place list items in a ListBox or controls or other Ul 
elements in a DockPanel, you also use the Items and Children properties, either explicitly or implicitly, as in the 
following example. 





<Docl<Panel 


Name="ParentElement" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

< ! - -implicit: <Docl<Panel.Children>--> 

<ListBox Docl<Panel.Dock="Top"> 

<!--implicit: <ListBox.Items>--> 

<ListBoxItem> 

<TextBlock>Dog</TextBlock) 

</ListBoxItem> 

<ListBoxItem> 

<TextBlock>Cat</TextBlock) 

</ListBoxItem) 

<ListBoxItem) 

<TextBlock)Fish</TextBlock) 

</ListBoxItem) 

<!--implicit: </ListBox.Items)--) 

</ListBox) 

<Button Height="20" Width="100" DockPanel.Dock="Top")Buy a Pet</Button) 
<!--implicit: </DockPanel.Children)--) 

</DockPanel) 


If you were to process this XAML as XML under a document object model, and if you had included the tags 
commented out as implicit (which would have been legal), then the resulting XML DOM tree would have included 
elements for <ListBox.items) and the other implicit items. But XAML does not process that way when you read 
the markup and write to objects, the resulting object graph does not literally include listBox.items . It does 
however have a ListBox property named items that contains a ItemCollection, and that ItemCollection is 
initialized but empty when the ListBox XAML is processed. Then, each child object element that exists as content 
for the ListBox is added to the ItemCollection by parser calls to ItemCollection.Add . This example of processing 
XAML into an object tree is so far seemingly an example where the created object tree is basically the logical tree. 

However, the logical tree is not the entire object graph that exists for your application Ul at run time, even with 
the XAML implicit syntax items factored out. The main reason for this is visuals and templates. For example, 
consider the Button. The logical tree reports the Button object and also its string content . But there is more to 
this button in the run-time object tree. In particular, the button only appears on screen the way it does because a 
specific Button control template was applied. The visuals that come from an applied template (such as the 
template-defined Border of dark gray around the visual button) are not reported in the logical tree, even if you 
are looking at the logical tree during run time (such as handling an input event from the visible Ul and then 
reading the logical tree). To find the template visuals, you would instead need to examine the visual tree. 

For more information about how XAML syntax maps to the created object graph, and implicit syntax in XAML, see 
XAML Syntax In Detail or XAML Overview (WPF). 

The Purpose of the Logical Tree 

The logical tree exists so that content models can readily iterate over their possible child objects, and so that 
content models can be extensible. Also, the logical tree provides a framework for certain notifications, such as 
when all objects in the logical tree are loaded. Basically, the logical tree is an approximation of a run time object 
graph at the framework level, which excludes visuals, but is adequate for many querying operations against your 
own run time application's composition. 

In addition, both static and dynamic resource references are resolved by looking upwards through the logical tree 
for Resources collections on the initial requesting object, and then continuing up the logical tree and checking 
each FrameworkElement (or FrameworkContentElement) for another Resources value that contains a 
ResourceDictionary, possibly containing that key. The logical tree is used for resource lookup when both the 
logical tree and the visual tree are present. For more information on resource dictionaries and lookup, see XAML 
Resources. 








Composition of the Logical Tree 

The logical tree is defined at the WPF framework-level, which means that the WPF base element that is most 
relevant for logical tree operations is either FrameworkElement or FrameworkContentElement. However, as you 
can see if you actually use the LogicalTreeHelper API, the logical tree sometimes contains nodes that are not 
either FrameworkElement or FrameworkContentElement. For instance, the logical tree reports the Text value of a 
TextBlock, which is a string. 

Overriding the Logical Tree 

Advanced control authors can override the logical tree by overriding several APIs that define how a general 
object or content model adds or removes objects within the logical tree. For an example of how to override the 
logical tree, see Override the Logical Tree. 

Property Value Inheritance 

Property value inheritance operates through a hybrid tree. The actual metadata that contains the Inherits 
property that enables property inheritance is the WPF framework-level FrameworkPropertyMetadata class. 
Therefore, both the parent that holds the original value and the child object that inherits that value must both be 
FrameworkElement or FrameworkContentElement, and they must both be part of some logical tree. However, for 
existing WPF properties that support property inheritance, property value inheritance is able to perpetuate 
through an intervening object that is not in the logical tree. Mainly this is relevant for having template elements 
use any inherited property values set either on the instance that is templated, or at still higher levels of page-level 
composition and therefore higher in the logical tree. In order for property value inheritance to work consistently 
across such a boundary, the inheriting property must be registered as an attached property, and you should 
follow this pattern if you intend to define a custom dependency property with property inheritance behavior. The 
exact tree used for property inheritance cannot be entirely anticipated by a helper class utility method, even at 
run time. For more information, see Property Value Inheritance. 

The Visual Tree 

In addition to the concept of the logical tree, there is also the concept of the visual tree in WPF. The visual tree 
describes the structure of visual objects, as represented by the Visual base class. When you write a template for a 
control, you are defining or redefining the visual tree that applies for that control. The visual tree is also of 
interest to developers who want lower-level control over drawing for performance and optimization reasons. One 
exposure of the visual tree as part of conventional WPF application programming is that event routes for a 
routed event mostly travel along the visual tree, not the logical tree. This subtlety of routed event behavior might 
not be immediately apparent unless you are a control author. Routing events through the visual tree enables 
controls that implement composition at the visual level to handle events or create event setters. 

Trees, Content Elements, and Content Hosts 

Content elements (classes that derive from ContentElement) are not part of the visual tree; they do not inherit 
from Visual and do not have a visual representation. In order to appear in a Ul at all, a ContentElement must be 
hosted in a content host that is both a Visual and a logical tree participant. Usually such an object is a 
FrameworkElement. You can conceptualize that the content host is somewhat like a "browser" for the content and 
chooses how to display that content within the screen region that the host controls. When the content is hosted, 
the content can be made a participant in certain tree processes that are normally associated with the visual tree. 
Generally, the FrameworkElement host class includes implementation code that adds any hosted ContentElement 
to the event route through subnodes of the content logical tree, even though the hosted content is not part of the 
true visual tree. This is necessary so that a ContentElement can source a routed event that routes to any element 
other than itself 

Tree Traversal 

The LogicalTreeHelper class provides the GetChildren, GetParent, and FindLogicalNode methods for logical tree 


traversal. In most cases, you should not have to traverse the logical tree of existing controls, because these 
controls almost always expose their logical child elements as a dedicated collection property that supports 
collection access such as Add , an indexer, and so on. Tree traversal is mainly a scenario that is used by control 
authors who choose not to derive from intended control patterns such as ItemsControl or Panel where collection 
properties are already defined, and who intend to provide their own collection property support. 

The visual tree also supports a helper class for visual tree traversal, VisualTreeHelper. The visual tree is not 
exposed as conveniently through control-specific properties, so the VisualTreeHelper class is the recommended 
way to traverse the visual tree if that is necessary for your programming scenario. For more information, see 
WPF Graphics Rendering Overview. 


NOTE 

Sometimes it is necessary to examine the visual tree of an applied template. You should be careful when using this 
technique. Even if you are traversing a visual tree for a control where you define the template, consumers of your control 
can always change the template by setting the Template property on instances, and even the end user can influence the 
applied template by changing the system theme. 


Routes for Routed Events as a "Tree" 

As mentioned before, the route of any given routed event travels along a single and predetermined path of a tree 
that is a hybrid of the visual and logical tree representations. The event route can travel either in the up or down 
directions within the tree depending on whether it is a tunneling or bubbling routed event. The event route 
concept does not have a directly supporting helper class that could be used to "walk" the event route 
independently of raising an event that actually routes. There is a class that represents the route, EventRoute, but 
the methods of that class are generally for internal use only. 

Resource Dictionaries and Trees 

Resource dictionary lookup for all Resources defined in a page traverses basically the logical tree. Objects that 
are not in the logical tree can reference keyed resources, but the resource lookup sequence begins at the point 
where that object is connected to the logical tree. In WPF, only logical tree nodes can have a Resources property 
that contains a ResourceDictionary, therefore there is no benefit in traversing the visual tree looking for keyed 
resources from a ResourceDictionary. 

However, resource lookup can also extend beyond the immediate logical tree. For application markup, the 
resource lookup can then continue onward to application-level resource dictionaries and then to theme support 
and system values that are referenced as static properties or keys. Themes themselves can also reference system 
values outside of the theme logical tree if the resource references are dynamic. For more information on resource 
dictionaries and the lookup logic, see XAML Resources. 

See also 

• Input Overview 

• WPF Graphics Rendering Overview 

• Routed Events Overview 

• Initialization for Object Elements Not in an Object Tree 

• WPF Architecture 
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The API Save can be used to serialize the contents of a Windows Presentation Foundation (WPF) application as a 
Extensible Application Markup Language (XAML) file. However, there are some notable limitations in exactly what is 
serialized. These limitations and some general considerations are documented in this topic. 

Run-Time, Not Design-Time Representation 

The basic philosophy of what is serialized by a call to Save is that the result will be a representation of the object 
being serialized, at run-time. Many design-time properties of the original XAML file may already be optimized or 
lost by the time that the XAML is loaded as in-memory objects, and are not preserved when you call Save to 
serialize. The serialized result is an effective representation of the constructed logical tree of the application, but not 
necessarily of the original XAML that produced it. These issues make it extremely difficult to use the Save 
serialization as part of an extensive XAML design surface. 

Serialization is Self-Contained 

The serialized output of Save is self-contained; everything that is serialized is contained inside a XAML single page, 
with a single root element, and no external references other than URIs. For instance, if your page referenced 
resources from application resources, these will appear as if they were a component of the page being serialized. 

Extension References are Dereferenced 

Common references to objects made by various markup extension formats, such as staticResour-ce or Binding , 
will be dereferenced by the serialization process. These were already dereferenced at the time that in-memory 
objects were created by the application runtime, and the Save logic does not revisit the original XAML to restore 
such references to the serialized output. This potentially freezes any databound or resource obtained value to be 
the value last used by the run-time representation, with only limited or indirect ability to distinguish such a value 
from any other value set locally. Images are also serialized as object references to images as they exist in the 
project, rather than as original source references, losing whatever filename or URI was originally referenced. Even 
resources declared within the same page are seen serialized into the point where they were referenced, rather than 
being preserved as a key of a resource collection. 

Event Handling is Not Preserved 

When event handlers that are added through XAML are serialized, they are not preserved. XAML without code- 
behind (and also without the related x:Code mechanism) has no way of serializing runtime procedural logic. 
Because serialization is self-contained and limited to the logical tree, there is no facility for storing the event 
handlers. As a result, event handler attributes, both the attribute itself and the string value that names the handler, 
are removed from the output XAML. 

Realistic Scenarios for Use of XAMLWriter.Save 

While the limitations listed here are fairly substantial, there are still several appropriate scenarios for using Save for 
serialization. 

• Vector or graphical output: The output of the rendered area can be used to reproduce the same vector or 
graphics when reloaded. 






Rich text and flow docunnents: Text and all element formatting and element containment within it is 
preserved in the output. This can be useful for mechanisms that approximate a clipboard functionality. 

Preserving business object data: If you have stored data in custom elements, such as XML data, so long as 
your business objects follow basic XAML rules such as providing custom constructors and conversion for 
by-reference property values, these business objects can be perpetuated through serialization. 
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Some aspects of Windows Presentation Foundation (WPF) initialization are deferred to processes that typically rely 
on that element being connected to either the logical tree or visual tree. This topic describes the steps that may be 
necessary in order to initialize an element that is not connected to either tree. 

Elements and the Logical Tree 

When you create an instance of a Windows Presentation Foundation (WPF) class in code, you should be aware that 
several aspects of object initialization for a Windows Presentation Foundation (WPF) class are deliberately not a 
part of the code that is executed when calling the class constructor. Particularly for a control class, most of the 
visual representation of that control is not defined by the constructor. Instead, the visual representation is defined 
by the control's template. The template potentially comes from a variety of sources, but most often the template is 
obtained from theme styles. Templates are effectively late-binding; the necessary template is not attached to the 
control in question until the control is ready for layout And the control is not ready for layout until it is attached to 
a logical tree that connects to a rendering surface at the root It is that root-level element that initiates the 
rendering of all of its child elements as defined in the logical tree. 

The visual tree also participates in this process. Elements that are part of the visual tree through the templates are 
also not fully instantiated until connected. 

The consequences of this behavior are that certain operations that rely on the completed visual characteristics of 
an element require additional steps. An example is if you are attempting to get the visual characteristics of a class 
that was constructed but not yet attached to a tree. For instance, if you want to call Render on a 
RenderTargetBitmap and the visual you are passing is an element not connected to a tree, that element is not 
visually complete until additional initialization steps are completed. 

Using Begininitand Endinitto Initialize the Element 

Various classes in WPF implement the ISupportInitialize interface. You use the Begininit and Endinit methods of the 
interface to denote a region in your code that contains initialization steps (such as setting property values that 
affect rendering). After Endinit is called in the sequence, the layout system can process the element and start 
looking for an implicit style. 

If the element you are setting properties on is a FrameworkElement or FrameworkContentElement derived class, 
then you can call the class versions of Begininit and Endinit rather than casting to ISupportInitialize. 

Sample Code 

The following example is sample code for a console application that uses rendering APIs and 
XamlReader.Load(Stream) of a loose XAML file to illustrate the proper placement of Begininit and Endinit around 
other API calls that adjust properties that affect rendering. 

The example illustrates the main function only. The functions Rasterize and save (not shown) are utility 
functions that take care of image processing and 10. 






[STAThread] 

static void Main(string[] args) 

{ 

UIElement e; 

string file = Directory.GetCurrentDirectoryO + "Wstarting.xaml"; 
using (Stream stream = File.Open(filej FileMode.Open)) 

{ 

// loading files from current directory, project settings take care of copying the file 
ParserContext pc = new ParserContext()j 
pc.BaseUri = new Uri(file, UriKind.Absolute)j 
e = (UIFlement)XamlReader.Load(stream, pc)j 

} 

Size paperSize = new Size(8.5 * 96, 11 * 96)j 
e.Measure(paperSize); 
e.Arrange(new Rect(paperSize)); 
e.UpdateLayout(); 

/* 

* Render effect at normal dpi, indicator is the original RFD rectangle 
*/ 

RenderTargetBitmap imagel = Rasterize(e, paperSize.Width, paperSize.Height, 96, 96); 
Save(imagel, "renderl.png"); 

Button b = new Button(); 
b.BeginInitO; 

b.Background = Brushes.Blue; 
b.Width = b.Height = 200; 
b.EndInitO; 
b.Measure(paperSize); 
b.Arrange(new Rect(paperSize)); 
b.UpdateLayout(); 

// now render the altered version, with the element built up and initialized 

RenderTargetBitmap imagel = Rasterize(b, paperSize.Width, paperSize.Height, 96, 96); 
Save(image2, "renderl.png"); 



<STAThread> 

Shared Sub Main(By\/al args() As String) 

Dim e As UIElement 

Dim _file As String = Directory.GetCurrentDirectoryO & "\starting.xaml" 

Using stream As Stream = File.Open(_filej FileMode.Open) 

' loading files from current directoryj project settings take care of copying the file 

Dim pc As New ParserContext() 

pc.BaseUri = New Uri(_file^ UriKind.Absolute) 

e = CType(XamlReader.Load(streamj pc), UIElement) 

End Using 

Dim paperSize As New Size(8.5 * 96, 11 * 96) 
e.Measure(paperSize) 
e.Arrange(New Rect(paperSize)) 
e.UpdateLayout 0 

' * Render effect at normal dpi, indicator is the original RED rectangle 

Dim imagel As RenderTargetBitmap = Rasterize(e, paperSize.Width, paperSize.Height, 96, 96) 
Save(imagel, "renderl.png") 

Dim b As New Button() 
b.BeginInitO 

b.Background = Brushes.Blue 

b.Height = 200 

b.Width = b.Height 

b.EndInitO 

b.Measure(paperSize) 

b.Arrange(New Rect(paperSize)) 

b.UpdateLayoutO 

' now render the altered version, with the element built up and initialized 

Dim image2 As RenderTargetBitmap = Rasterize(b, paperSize.Width, paperSize.Height, 96, 96) 
Save(image2, "render2.png") 

End Sub 


See also 

• Trees in WPF 

• WPF Graphics Rendering Overview 

• XAML Overview (WPF) 
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The topics in this section describe how to use the WPF element tree. 

In This Section 

Find an Element by Its Name 
Override the Logical Tree 
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LogicalTreeHelper 
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Related Sections 
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This example describes how to use the FindName method to find an element by its Name value. 

Example 

In this example, the method to find a particular element by its name is written as the event handler of a button. 
stackPanei is the Name of the root FrameworkElement being searched, and the example method then visually 
indicates the found element by casting it as TextBlock and changing one of the TextBlock visible Ul properties. 

void Find(object senderj RoutedEventAngs e) 

{ 

object wantedNode = stackPanei.FindName("dog")j 
if (wantedNode is TextBlock) 

{ 

// Following executed if Text element was found. 

TextBlock wantedChild = wantedNode as TextBlock; 
wantedChild.Foreground = Brushes.Blue; 

} 

} 


Private Sub Find(ByVal sender As Objectj ByVal e As RoutedEventArgs) 
Dim wantedNode As Object = stackPanei.FindName("dog") 

If TypeOf wantedNode Is TextBlock Then 

' Following executed if Text element was found. 

Dim wantedChild As TextBlock = TryCast(wantedNode, TextBlock) 
wantedChild.Foreground = Brushes.Blue 
End If 
End Sub 
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Although it is not necessary in most cases, advanced control authors have the option to override the logical tree. 

Example 

This example describes how to subclass StackPanel to override the logical tree, in this case to enforce a behavior 
that the panel may only have and will only render a single child element. This isn't necessarily a practically 
desirable behavior, but is shown here as a means of illustrating the scenario for overriding an element's normal 
logical tree. 

public class SingletonPanel : StackPanel 

{ 

//private UIElementCollection _children; 
private FrameworkElement _child; 

public SingletonPanel() 

{ 

} 

public ErameworkElement SingleChild 

{ 

get { return _child; } 

set 

{ 

if (value == null) 

{ 

RemoveLogicalChild(_child); 

} 

else 

{ 

if (_child == null) 

{ 

_child = value; 

} 

else 

{ 

// raise an exception? 

MessageBox.Show("Needs to be a single element"); 

} 

} 

} 

} 

public void SetSingleChild(object child) 

{ 

this.AddLogicalChild(child); 

} 

public new void AddLogicalChild(object child) 

{ 

_child = (FrameworkElement)child; 
if (this.Children.Count == 1) 

{ 

this.RemoveLogicalChild(this.Children[0]); 
this.Children.Add((UIElement)child); 

} 

else 

{ 




} 


this.Children.Add((UIElement)child); 


} 

public new void RemoveLogicalChild(object child) 

{ 

_chlld = null; 
this. Children. Clear 0; 

} 

protected override lEnumerator LogicalChildren 

{ 

get 

{ 

// cheatj make a list with one member and return the enumerator 
ArrayList _list = new ArrayList(); 

_list.Add(_child); 

return (IEnumerator)_list.GetEnumerator(); 

} 

} 


For more information on the logical tree, see Trees in WPF. 
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Windows Presentation Foundation (WPF) provides a set of services that can be used to extend the functionality of 
a common language runtime (CLR) property. Collectively, these services are typically referred to as the WPF 
property system. A property that is backed by the WPF property system is known as a dependency property. 
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Windows Presentation Foundation (WPF) provides a set of services that can be used to extend the 
functionality of a type's property. Collectively, these services are typically referred to as the WPF property 
system. A property that is backed by the WPF property system is known as a dependency property. This 
overview describes the WPF property system and the capabilities of a dependency property. This includes 
how to use existing dependency properties in XAML and in code. This overview also introduces specialized 
aspects of dependency properties, such as dependency property metadata, and how to create your own 
dependency property in a custom class. 

Prerequisites 

This topic assumes that you have some basic knowledge of the .NET type system and object-oriented 
programming. In order to follow the examples in this topic, you should also understand XAML and know how 
to write WPF applications. For more information, see Walkthrough: My first WPF desktop application. 

Dependency properties and CLR properties 

In WPF, properties are typically exposed as standard .NET properties. At a basic level, you could interact with 
these properties directly and never know that they are implemented as a dependency property. However, you 
should become familiar with some or all of the features of the WPF property system, so that you can take 
advantage of these features. 

The purpose of dependency properties is to provide a way to compute the value of a property based on the 
value of other inputs. These other inputs might include system properties such as themes and user 
preference,Just-in-time property determination mechanisms such as data binding and 
animations/storyboards, multiple-use templates such as resources and styles, or values known through 
parent-child relationships with other elements in the element tree. In addition, a dependency property can be 
implemented to provide self-contained validation, default values, callbacks that monitor changes to other 
properties, and a system that can coerce property values based on potentially runtime information. Derived 
classes can also change some specific characteristics of an existing property by overriding dependency 
property metadata, rather than overriding the actual implementation of existing properties or creating new 
properties. 

In the SDK reference, you can identify which property is a dependency property by the presence of the 
Dependency Property Information section on the managed reference page for that property. The Dependency 
Property Information section includes a link to the DependencyProperty identifier field for that dependency 
property, and also includes a list of the metadata options that are set for that property, per-class override 
information, and other details. 

Dependency properties back CLR properties 

Dependency properties and the WPF property system extend property functionality by providing a type that 
backs a property, as an alternative implementation to the standard pattern of backing the property with a 
private field. The name of this type is DependencyProperty. The other important type that defines the WPF 
property system is DependencyObject. DependencyObject defines the base class that can register and own a 
dependency property. 

The following lists the terminology that is used with dependency properties: 




• Dependency property: A property that is backed by a DependencyProperty. 


• Dependency property identifier: A DependencyProperty instance, which is obtained as a return 
value when registering a dependency property, and then stored as a static member of a class. This 
identifier is used as a parameter for many of the APIs that interact with the WPF property system. 

• CLR "wrapper": The actual get and set implementations for the property. These implementations 
incorporate the dependency property identifier by using it in the GetValue and SetValue calls, thus 
providing the backing for the property using the WPF property system. 

The following example defines the isSpinning dependency property, and shows the relationship of the 
DependencyProperty identifier to the property that it backs. 

public static readonly DependencyProperty IsSpinningProperty = 

DependencyProperty.Register( 

"IsSpinning"j typeof(Boolean)^ 
typeof(MyCode) 

); 

public bool IsSpinning 
{ 

get { return (bool)GetValue(IsSpinningProperty)j } 
set { SetValue(IsSpinningProperty^ value)j } 

} 


Public Shared Readonly IsSpinningProperty As DependencyProperty = 
DependencyProperty.Register("IsSpinning", 

GetType(Boolean), 

GetType(MyCode)) 

Public Property IsSpinningO As Boolean 
Get 

Return CBool(GetValue(IsSpinningProperty)) 

End Get 

Set(ByVal value As Boolean) 

SetValue(IsSpinningProperty, value) 

End Set 
End Property 


The naming convention of the property and its backing DependencyProperty field is important. The name of 
the field is always the name of the property, with the suffix Property appended. For more information about 
this convention and the reasons for it, see Custom Dependency Properties. 

Setting property values 

You can set properties either in code or in XAML. 

Setting property values in XAML 

The following XAML example specifies the background color of a button as red. This example illustrates a case 
where the simple string value for a XAML attribute is type-converted by the WPF XAML parser into a WPF 
type (a Color, by way of a SolidColorBrush) in the generated code. 

<Button Background="Red" Content="Button!"/> 


XAML supports a variety of syntax forms for setting properties. Which syntax to use for a particular property 
will depend on the value type that a property uses, as well as other factors such as the presence of a type 
converter. For more information on XAML syntax for property setting, see XAML Overview (WPF) and XAML 
Syntax In Detail. 






As an example of non-attribute syntax, the following XAML example shows another button background. This 
time rather than setting a simple solid color, the background is set to an image, with an element representing 
that image and the source of that image specified as an attribute of the nested element. This is an example of 
property element syntax. 


<Button Content="Button!"> 

<Button.Background> 

cImageBrush ImageSource="wavy.jpg"/> 
</Button.Background> 

</Button> 


Setting properties in code 

Setting dependency property values in code is typically just a call to the set implementation exposed by the 
CLR "wrapper". 

Button myButton = new Button(); 
myButton.Width = 200.0; 


Dim myButton As New Button() 
myButton.Width = 200.0 

Getting a property value is also essentially a call to the get "wrapper" implementation: 

double whatWidth; 
whatWidth = myButton.Width; 


Dim whatWidth As Double 
whatWidth = myButton.Width 

You can also call the property system APIs GetValue and SetValue directly. This is not typically necessary if you 
are using existing properties (the wrappers are more convenient, and provide better exposure of the property 
for developer tools), but calling the APIs directly is appropriate for certain scenarios. 

Properties can be also set in XAML and then accessed later in code, through code-behind. For details, see 
Code-Behind and XAML in WPF. 

Property functionality provided by a dependency property 

A dependency property provides functionality that extends the functionality of a property as opposed to a 
property that is backed by a field. Often, such functionality represents or supports one of the following 
specific features: 

• Resources 

• Data binding 

• Styles 

• Animations 

• Metadata overrides 


• Property value inheritance 





• WPF Designer integration 


Resources 

A dependency property value can be set by referencing a resource. Resources are typically specified as the 
Resources property value of a page root element, or of the application (these locations enable the most 
convenient access to the resource). The following example shows how to define a SolidColorBrush resource. 

cDockPanel.Resources> 

<SolidColorBrush x:Key="MyBrush" Color="Gold"/> 

</DockPanel.Resources> 

Once the resource is defined, you can reference the resource and use it to provide a property value: 

<Button Background="{DynamicResource MyBrush}" Content="I am gold" /> 

This particular resource is referenced as a DynamicResource Markup Extension (in WPF XAML, you can use 
either a static or dynamic resource reference). To use a dynamic resource reference, you must be setting to a 
dependency property, so it is specifically the dynamic resource reference usage that is enabled by the WPF 
property system. For more information, see XAML Resources. 


NOTE 

Resources are treated as a local value, which means that if you set another local value, you will eliminate the resource 
reference. For more information, see Dependency Property Value Precedence. 


Data binding 

A dependency property can reference a value through data binding. Data binding works through a specific 
markup extension syntax in XAML, or the Binding object in code. With data binding, the final property value 
determination is deferred until run time, at which time the value is obtained from a data source. 

The following example sets the Content property for a Button, using a binding declared in XAML. The binding 
uses an inherited data context and an XmlDataProvider data source (not shown). The binding itself specifies 
the desired source property by XPath within the data source. 


<Button Content="{Binding XPath=Team/@TeamName}"/> 



Dependency properties, or the DependencyObJect class, do not natively support INotifyPropertyChanged for 
purposes of producing notifications of changes in DependencyObJect source property value for data binding 
operations. For more information on how to create properties for use in data binding that can report changes 
to a data binding target, see Data Binding Overview. 

Styles 

Styles and templates are two of the chief motivating scenarios for using dependency properties. Styles are 
particularly useful for setting properties that define application user interface (Ul). Styles are typically defined 
as resources in XAML. Styles interact with the property system because they typically contain "setters" for 
particular properties, as well as "triggers" that change a property value based on the real-time value for 







another property. 

The following example creates a simple style (which would be defined inside a Resources dictionary, not 
shown), then applies that style directly to the Style property for a Button. The setter within the style sets the 
Background property for a styled Button to green. 

<Style x:Key="GreenButtonStyle"> 

<Setten Property="Contnol.Background" Value="Green"/> 

</Style> 

<Button Style="{StaticResource GreenButtonStyle}">I am green!</Button> 


For more information, see Styling and Templating. 

Animations 

Dependency properties can be animated. When an animation is applied and is running, the animated value 
operates at a higher precedence than any value (such as a local value) that the property otherwise has. 

The following example animates the Background on a Button property (technically, the Background is 
animated by using property element syntax to specify a blank SolidColorBrush as the Background, then the 
Color property of that SolidColorBrush is the property that is directly animated). 

<Button>I am animated 
<Button.Background> 

<SolidColorBrush x:Name="AnimBrush"/> 

</Button.Background> 

<Button.Triggers> 

<EventTrigger RoutedEvent="Button.Loaded"> 

<BeginStoryboard> 

<Storyboard> 

<ColorAnimation 

Storyboard.TargetName="AnimBrush" 

Storyboard.TargetProperty="(SolidColorBrush.Color)" 

From="Red" To="Green" Duration="0:0:5" 

AutoReverse="True" RepeatBehavior="Forever" /> 

</Storyboard> 

</BeginStoryboard) 

</EventTrigger> 

</Button.Triggers) 

</Button) 


For more information on animating properties, see Animation Overview and Storyboards Overview. 

Metadata overrides 

You can change certain behaviors of a dependency property by overriding the metadata for that property 
when you derive from the class that originally registers the dependency property. Overriding metadata relies 
on the DependencyProperty identifier. Overriding metadata does not require reimplementing the property. 
The metadata change is handled natively by the property system; each class potentially holds individual 
metadata for all properties that are inherited from base classes, on a per-type basis. 

The following example overrides metadata for a dependency property DefaultStyleKey. Overriding this 
particular dependency property metadata is part of an implementation pattern that creates controls that can 
use default styles from themes. 




public class SpinnerContnol : ItemsControl 
{ 

static SpinnerContnolO 
{ 

DefaultStyleKeyProperty.OvernideMetadata( 
typeof(SpinnerControl)j 

new FrameworkPropertyMetadata(typeof(SpinnerControl)) 

); 

} 


Public Class SpinnerControl 
Inherits ItemsControl 
Shared Sub New() 

DefaultStyleKeyProperty.OverrideMetadata(GetType(SpinnerControl)j New 
FrameworkPropertyMetadata(GetType(SpinnerControl))) 

End Sub 
End Class 


For more information about overriding or obtaining property metadata, see Dependency Property Metadata. 

Property value inheritance 

An element can inherit the value of a dependency property from its parent in the object tree. 


NOTE 

Property value inheritance behavior is not globally enabled for all dependency properties, because the calculation time 
for inheritance does have some performance impact. Property value inheritance is typically only enabled for properties 
where a particular scenario suggests that property value inheritance is appropriate. You can determine whether a 
dependency property inherits by looking at the Dependency Property Information section for that dependency 
property in the SDK reference. 


The following example shows a binding, and sets the DataContext property that specifies the source of the 
binding, which was not shown in the earlier binding example. Any subsequent bindings in child objects do not 
need to specify the source, they can use the inherited value from DataContext in the parent StackPanel object. 
(Alternatively, a child object could instead choose to directly specify its own DataContext or a Source in the 
Binding, and to deliberately not use the inherited value for data context of its bindings.) 

<StackPanel Canvas.Top="50" DataContext="{Binding Source={StaticResource XmlTeamsSource}}"> 

<Button Content="{Binding XPath=Team/@TeamName}"/> 

</StackPanel> 

For more information, see Property Value Inheritance. 

WPF designer integration 

A custom control with properties that are implemented as dependency properties will receive appropriate 
WPF Designer for Visual Studio support. One example is the ability to edit direct and attached dependency 
properties with the Properties window. For more information, see Control Authoring Overview. 

Dependency property value precedence 

When you get the value of a dependency property, you are potentially obtaining a value that was set on that 
property through any one of the other property-based inputs that participate in the WPF property system. 
Dependency property value precedence exists so that a variety of scenarios for how properties obtain their 
values can interact in a predictable way. 





Consider the following example. The example includes a style that applies to all buttons and their Background 
properties, but then also specifies one button with a locally set Background value. 


NOTE 

The SDK documentation uses the terms "local value" or "locally set value" occasionally when discussing dependency 
properties. A locally set value is a property value that is set directly on an object instance in code, or as an attribute on 
an element in XAML. 


In principle, for the first button, the property is set twice, but only one value applies: the value with the highest 
precedence. A locally set value has the highest precedence (except for a running animation, but no animation 
applies in this example) and thus the locally set value is used instead of the style setter value for the 
background on the first button. The second button has no local value (and no other value with higher 
precedence than a style setter) and thus the background in that button comes from the style setter. 

<StackPanel> 

<StackPanel.Resources) 

<Style x:Key="{x:Type Button}" TargetType="{x:Type Button}") 

<Setter Property="Background" Value="Red"/) 

</Style) 

</StackPanel.Resources) 

<Button Background="Green")I am NOT red!</Button) 

<Button)I am styled red</Button) 

</StackPanel) 


Why does dependency property precedence exist? 

Typically, you would not want styles to always apply and to obscure even a locally set value of an individual 
element (otherwise, it would be difficult to use either styles or elements in general). Therefore, the values that 
come from styles operate at a lower precedent than a locally set value. For a more thorough listing of 
dependency properties and where a dependency property effective value might come from, see Dependency 
Property Value Precedence. 


NOTE 

There are a number of properties defined on WPF elements that are not dependency properties. By and large, 
properties were implemented as dependency properties only when there were needs to support at least one of the 
scenarios enabled by the property system: data binding, styling, animation, default value support, inheritance, attached 
properties, or invalidation. 


Learning more about dependency properties 

• An attached property is a type of property that supports a specialized syntax in XAML. An attached 
property often does not have a 1:1 correspondence with a common language runtime (CLR) property, 
and is not necessarily a dependency property. The typical purpose of an attached property is to allow 
child elements to report property values to a parent element, even if the parent element and child 
element do not both possess that property as part of the class members listings. One primary scenario 
is to enable child elements to inform the parent how they should be presented in Ul; for an example, 
see Dock or Left. For details, see Attached Properties Overview. 

• Component developers or application developers may wish to create their own dependency property, 
in order to enable capabilities such as data binding or styles support, or for invalidation and value 
coercion support. For details, see Custom Dependency Properties. 

• Consider dependency properties to be public properties, accessible or at least discoverable by any 





caller that has access to an instance. For more information, see Dependency Property Security. 


See also 

• Custom Dependency Properties 

• Read-Only Dependency Properties 

• XAML Overview (WPF) 

• WPF Architecture 
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An attached property is a concept defined by XAML. An attached property is intended to be used as a type of 
global property that is settable on any object. In Windows Presentation Foundation (WPF), attached properties are 
typically defined as a specialized form of dependency property that does not have the conventional property 
"wrapper". 

Prerequisites 

This article assumes that you understand dependency properties from the perspective of a consumer of existing 
dependency properties on Windows Presentation Foundation (WPF) classes, and have read the Dependency 
Properties Overview. To follow the examples in this article, you should also understand XAML and know how to 
write WPF applications. 

Why Use Attached Properties 

One purpose of an attached property is to allow different child elements to specify unique values for a property 
that's defined in a parent element. A specific application of this scenario is having child elements inform the parent 
element of how they are to be presented in the user interface (Ul). One example is the DockPanel.Dock property. 
The DockPanel.Dock property is created as an attached property because it is designed to be set on elements that 
are contained within a DockPanel rather than on DockPanel itself The DockPanel class defines the static 
DependencyProperty field named DockProperty, and then provides the GetDock and SetDock methods as public 
accessors for the attached property. 

Attached Properties in XAML 

In XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName 
The following is an example of how you can set DockPanel.Dock in XAML: 

<DockPanel> 

<CheckBox DockPanel.Dock="Top">Hello</CheckBox> 

</DockPanel> 

The usage is somewhat similar to a static property; you always reference the type DockPanel that owns and 
registers the attached property, rather than referring to any instance specified by name. 

Also, because an attached property in XAML is an attribute that you set in markup, only the set operation has any 
relevance. You cannot directly get a property in XAML, although there are some indirect mechanisms for 
comparing values, such as triggers in styles (for details, see Styling and Templating). 

Attached Property Implementation in WPF 

In Windows Presentation Foundation (WPF), most of the Ul-related attached properties on WPF types are 
implemented as dependency properties. Attached properties are a XAML concept, whereas dependency properties 
are a WPF concept. Because WPF attached properties are dependency properties, they support dependency 
property concepts such as property metadata, and default values from that property metadata. 


How Attached Properties Are Used by the Owning Type 





Although attached properties are settable on any object, that does not automatically mean that setting the 
property will produce a tangible result, or that the value will ever be used by another object. Generally, attached 
properties are intended so that objects coming from a wide variety of possible class hierarchies or logical 
relationships can each report common information to the type that defines the attached property. The type that 
defines the attached property typically follows one of these models: 

• The type that defines the attached property is designed so that it can be the parent element of the elements 
that will set values for the attached property. The type then iterates its child objects through internal logic 
against some object tree structure, obtains the values, and acts on those values in some manner. 

• The type that defines the attached property will be used as the child element for a variety of possible parent 
elements and content models. 

• The type that defines the attached property represents a service. Other types set values for the attached 
property. Then, when the element that set the property is evaluated in the context of the service, the 
attached property values are obtained through internal logic of the service class. 

An Example of a Parent-Defined Attached Property 

The most typical scenario where WPF defines an attached property is when a parent element supports a child 
element collection, and also implements a behavior where the specifics of the behavior are reported individually 
for each child element. 

DockPanel defines the DockPanel.Dock attached property, and DockPanel has class-level code as part of its 
rendering logic (specifically, MeasureOverride and ArrangeOverride). A DockPanel instance will always check to 
see whether any of its immediate child elements have set a value for DockPanel.Dock. If so, those values become 
input for the rendering logic applied to that particular child element. Nested DockPanel instances each treat their 
own immediate child element collections, but that behavior is implementation-specific to how DockPanel 
processes DockPanel.Dock values. It is theoretically possible to have attached properties that influence elements 
beyond the immediate parent. If the DockPanel.Dock attached property is set on an element that has no DockPanel 
parent element to act upon it, no error or exception is raised. This simply means that a global property value was 
set, but it has no current DockPanel parent that could consume the information. 

Attached Properties in Code 

Attached properties in WPF do not have the typical CLR "wrapper" methods for easy get/set access. This is 
because the attached property is not necessarily part of the CLR namespace for instances where the property is 
set. However, a XAML processor must be able to set those values when XAML is parsed. To support an effective 
attached property usage, the owner type of the attached property must implement dedicated accessor methods in 
the form Get_PropertyName_ and Set_PropertyName_. These dedicated accessor methods are also useful to 
get or set the attached property in code. From a code perspective, an attached property is similar to a backing field 
that has method accessors instead of property accessors, and that backing field can exist on any object rather than 
needing to be specifically defined. 

The following example shows how you can set an attached property in code. In this example, myChecksox is an 
instance of the CheckBox class. 

DockPanel myDockPanel = new DockPanel(); 

CheckBox myCheckBox = new CheckBox(); 
myCheckBox.Content = "Hello"; 
myDockPanel.Children.Add(myCheckBox); 

DockPanel.SetDock(myCheckBoXj Dock.Top); 





fourth line of code, the fifth line of code would not raise an exception, but the property value would not interact 
with a DockPanel parent and thus would do nothing. Only a DockPanel.Dock value set on a child element 
combined with the presence of a DockPanel parent element will cause an effective behavior in the rendered 
application. (In this case, you could set the attached property, then attach to the tree. Or you could attach to the 
tree then set the attached property. Either action order provides the same result.) 

Attached Property Metadata 

When registering the property, FrameworkPropertyMetadata is set to specify characteristics of the property, such 
as whether the property affects rendering, measurement, and so on. Metadata for an attached property is 
generally no different than on a dependency property. If you specify a default value in an override to attached 
property metadata, that value becomes the default value of the implicit attached property on instances of the 
overriding class. Specifically, your default value is reported if some process queries for the value of an attached 
property through the Get method accessor for that property, specifying an instance of the class where you 
specified the metadata, and the value for that attached property was otherwise not set. 

If you want to enable property value inheritance on a property, you should use attached properties rather than 
non-attached dependency properties. For details, see Property Value Inheritance. 

Custom Attached Properties 

When to Create an Attached Property 

You might create an attached property when there is a reason to have a property setting mechanism available for 
classes other than the defining class. The most common scenario for this is layout. Examples of existing layout 
properties are DockPanel.Dock, Panel.ZIndex, and Canvas.Top. The scenario enabled here is that elements that exist 
as child elements to layout-controlling elements are able to express layout requirements to their layout parent 
elements individually, each setting a property value that the parent defined as an attached property. 

Another scenario for using an attached property is when your class represents a service, and you want classes to 
be able to integrate the service more transparently. 

Yet another scenario is to receive Visual Studio WPF Designer support, such as Properties window editing. For 
more information, see Control Authoring Overview. 

As mentioned before, you should register as an attached property if you want to use property value inheritance. 

How to Create an Attached Property 

If your class is defining the attached property strictly for use on other types, then the class does not have to derive 
from DependencyObject. But you do need to derive from DependencyObject if you follow the overall WPF model 
of having your attached property also be a dependency property. 

Define your attached property as a dependency property by declaring a public static readonly field of type 
DependencyProperty. You define this field by using the return value of the RegisterAttached method. The field 
name must match the attached property name, appended with the string Property , to follow the established WPF 
pattern of naming the identifying fields versus the properties that they represent. The attached property provider 
must also provide static Get_PropertyName_ and Set_PropertyName_ methods as accessors for the attached 
property; failing to do this results in the property system being unable to use your attached property. 








NOTE 

If you omit the attached property's get accessor, data binding on the property will not work in design tools, such as Visual 
Studio and Blend for Visual Studio. 


The Get Accessor 

The signature for the Get_PropertyName_ accessor must be: 

public static object GetPropertyName(object target) 

• The target object can be specified as a more specific type in your implementation. For example, the 
DockPanel.GetDock method types the parameter as UlElement, because the attached property is only 
intended to be set on UlElement instances. 

• The return value can be specified as a more specific type in your implementation. For example, the GetDock 
method types it as Dock, because the value can only be set to that enumeration. 

The Set Accessor 

The signature for the Set_PropertyName_ accessor must be: 

public static void SetPropertyName(object target, object value) 

• The target object can be specified as a more Specific type in your implementation. For example, the 
SetDock method types it as UlElement, because the attached property is only intended to be set on 
UlElement instances. 

• The value object can be specified as a more specific type in your implementation. For example, the 
SetDock method types it as Dock, because the value can only be set to that enumeration. Remember that 
the value for this method is the input coming from the XAML loader when it encounters your attached 
property in an attached property usage in markup. That input is the value specified as a XAML attribute 
value in markup. Therefore there must be type conversion, value serializer, or markup extension support for 
the type you use, such that the appropriate type can be created from the attribute value (which is ultimately 
just a string). 

The following example shows the dependency property registration (using the RegisterAttached method), as well 
as the Get_PropertyName_ and Set_PropertyName_ accessors. In the example, the attached property name is 
IsBubbleSource . Therefore, the accessors must be named GetlsBubbleSource and SetlsBubbleSource . 

public static readonly DependencyProperty IsBubbleSourceProperty = DependencyProperty.RegisterAttached( 
"IsBubbleSource", 
typeof(Boolean), 
typeof(AquariumObject), 

new FrameworkPropertyMetadataffalse, FrameworkPropertyMetadataOptions.AffectsRender) 

); 

public static void SetIsBubbleSource(UIElement element. Boolean value) 

{ 

element.SetValue(IsBubbleSourceProperty, value)j 

} 

public static Boolean GetIsBubbleSource(UIElement element) 

{ 

return (Boolean)element.GetValue(IsBubbleSourceProperty); 

} 










Public Shared Readonly IsBubbleSourceProperty As DependencyProperty = 

DependencyProperty.RegisterAttachedC'IsBubbleSource", GetType(Boolean), GetType(AquariumObject)j New 
FrameworkPropertyMetadata(False, FrameworkPropertyMetadataOptions.AffectsRender)) 

Public Shared Sub SetIsBubbleSource(ByVal element As UIElement, ByVal value As Boolean) 
element.Set\/alue(IsBubbleSourceProperty, value) 

End Sub 

Public Shared Function GetIsBubbleSource(ByVal element As UIElement) As Boolean 
Return CType(element.GetValue(IsBubbleSourceProperty), Boolean) 

End Function 

Attached Property Attributes 

WPF defines several .NET attributes that are intended to provide information about attached properties to 
reflection processes, and to typical users of reflection and property information such as designers. Because 
attached properties have a type of unlimited scope, designers need a way to avoid overwhelming users with a 
global list of all the attached properties that are defined in a particular technology implementation that uses 
XAML. The .NET attributes that WPF defines for attached properties can be used to scope the situations where a 
given attached property should be shown in a properties window. You might consider applying these attributes 
for your own custom attached properties also. The purpose and syntax of the .NET attributes is described on the 
appropriate reference pages: 

• AttachedPropertyBrowsableAttribute 

• AttachedPropertyBrowsableForChildrenAttribute 

• AttachedPropertyBrowsableForTypeAttribute 

• AttachedPropertyBrowsableWhenAttributePresentAttribute 

Learning More About Attached Properties 

• For more information on creating an attached property, see Register an Attached Property. 

• For more advanced usage scenarios for dependency properties and attached properties, see Custom 
Dependency Properties. 

• You can also register a property as an attached property, and as a dependency property, but then still 
expose "wrapper" implementations. In this case, the property can be set either on that element, or on any 
element through the XAML attached property syntax. An example of a property with an appropriate 
scenario for both standard and attached usages is FrameworkElement.FlowDirection. 

See also 

• DependencyProperty 

• Dependency Properties Overview 

• Custom Dependency Properties 

• XAML Overview (WPF) 

• Register an Attached Property 
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This topic describes the reasons that Windows Presentation Foundation (WPF) application developers and 
component authors might want to create custom dependency property, and describes the implementation 
steps as well as some implementation options that can improve performance, usability, or versatility of the 
property. 

Prerequisites 

This topic assumes that you understand dependency properties from the perspective of a consumer of 
existing dependency properties on WPF classes, and have read the Dependency Properties Overview topic. In 
order to follow the examples in this topic, you should also understand Extensible Application Markup 
Language (XAML) and know how to write WPF applications. 

What Is a Dependency Property? 

You can enable what would otherwise be a common language runtime (CLR) property to support styling, data 
binding, inheritance, animations, and default values by implementing it as a dependency property. 

Dependency properties are properties that are registered with the WPF property system by calling the 
Register method (or RegisterReadOnly), and that are backed by a DependencyProperty identifier field. 
Dependency properties can be used only by DependencyObject types, but DependencyObject is quite high in 
the WPF class hierarchy, so the majority of classes available in WPF can support dependency properties. For 
more information about dependency properties and some of the terminology and conventions used for 
describing them in this SDK, see Dependency Properties Overview. 

Examples of Dependency Properties 

Examples of dependency properties that are implemented on WPF classes include the Background property, 
the Width property, and the Text property, among many others. Each dependency property exposed by a class 
has a corresponding public static field of type DependencyProperty exposed on that same class. This is the 
identifier for the dependency property. The identifier is named using a convention: the name of the 
dependency property with the string Property appended to it For example, the corresponding 
DependencyProperty identifier field for the Background property is BackgroundProperty. The identifier stores 
the information about the dependency property as it was registered, and the identifier is then used later for 
other operations involving the dependency property, such as calling SetValue. 

As mentioned in the Dependency Properties Overview, all dependency properties in WPF (except most 
attached properties) are also CLR properties because of the "wrapper" implementation. Therefore, from code, 
you can get or set dependency properties by calling CLR accessors that define the wrappers in the same 
manner that you would use other CLR properties. As a consumer of established dependency properties, you 
do not typically use the DependencyObject methods GetValue and SetValue, which are the connection point to 
the underlying property system. Rather, the existing implementation of the CLR properties will have already 
called GetValue and SetValue within the get and set wrapper implementations of the property, using the 
identifier field appropriately. If you are implementing a custom dependency property yourself, then you will be 
defining the wrapper in a similar way. 

When Should You Implement a Dependency Property? 

When you implement a property on a class, so long as your class derives from DependencyObject, you have 







the option to back your property with a DependencyProperty identifier and thus to make it a dependency 
property. Having your property be a dependency property is not always necessary or appropriate, and will 
depend on your scenario needs. Sometimes, the typical technique of backing your property with a private field 
is adequate. However, you should implement your property as a dependency property whenever you want 
your property to support one or more of the following WPF capabilities: 

• You want your property to be settable in a style. For more information, see Styling and Templating. 

• You want your property to support data binding. For more information about data binding dependency 

properties, see Bind the Properties of Two Controls. 

• You want your property to be settable with a dynamic resource reference. For more information, see 
XAML Resources. 

• You want to inherit a property value automatically from a parent element in the element tree. In this 
case, register with the RegisterAttached method, even if you also create a property wrapper for CLR 
access. For more information, see Property Value Inheritance. 

• You want your property to be animatable. For more information, see Animation Overview. 

• You want the property system to report when the previous value of the property has been changed by 

actions taken by the property system, the environment, or the user, or by reading and using styles. By 
using property metadata, your property can specify a callback method that will be invoked each time 
the property system determines that your property value was definitively changed. A related concept is 
property value coercion. For more information, see Dependency Property Callbacks and Validation. 

• You want to use established metadata conventions that are also used by WPF processes, such as 
reporting whether changing a property value should require the layout system to recompose the 
visuals for an element. Or you want to be able to use metadata overrides so that derived classes can 
change metadata-based characteristics such as the default value. 

• You want properties of a custom control to receive Visual Studio WPF Designer support, such as 
Properties window editing. For more information, see Control Authoring Overview. 

When you examine these scenarios, you should also consider whether you can achieve your scenario by 
overriding the metadata of an existing dependency property, rather than implementing a completely new 
property. Whether a metadata override is practical depends on your scenario and how closely that scenario 
resembles the implementation in existing WPF dependency properties and classes. For more information 
about overriding metadata on existing properties, see Dependency Property Metadata. 

Checklist for Defining a Dependency Property 

Defining a dependency property consists of four distinct concepts. These concepts are not necessarily strict 
procedural steps, because some of these end up being combined as single lines of code in the 
implementation: 

• (Optional) Create property metadata for the dependency property. 

• Register the property name with the property system, specifying an owner type and the type of the 
property value. Also specify the property metadata, if used. 

• Define a DependencyProperty identifier as a public static readonly field on the owner type. 

• Define a CLR "wrapper" property whose name matches the name of the dependency property. 

Implement the CLR "wrapper" property's get and set accessors to connect with the dependency 
property that backs it. 

Registering the Property with the Property System 





In order for your property to be a dependency property, you must register that property into a table 
maintained by the property system, and give it a unique identifier that is used as the qualifier for later 
property system operations. These operations might be internal operations, or your own code calling property 
system APIs. To register the property, you call the Register method within the body of your class (inside the 
class, but outside of any member definitions). The identifier field is also provided by the Register method call, 
as the return value. The reason that the Register call is done outside of other member definitions is because 
you use this return value to assign and create a public static readonly field of type DependencyProperty 
as part of your class. This field becomes the identifier for your dependency property. 

public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register( 
"AquariumGraphic"j 
typeof(Uri)j 
typeof(AquariumObject)j 
new FrameworkPropertyMetadata(null, 

FrameworkPropertyMetadataOptions.AffectsRenderj 
new PropertyChangedCallback(OnUriChanged) 

) 

); 


Public Shared Readonly AquariumGraphicProperty As DependencyProperty = 

DependencyProperty.Register("AquariumGraphic", GetType(Llri), GetType(AquariumObject)j New 
FrameworkPropertyMetadata(Nothingj FrameworkPropertyMetadataOptions.AffectsRender, New 
PropertyChangedCallback(AddressOf OnUriChanged))) 


Dependency Property Name Conventions 

There are established naming conventions regarding dependency properties that you must follow in all but 
exceptional circumstances. 

The dependency property itself will have a basic name, "AquariumGraphic" as in this example, which is given 
as the first parameter of Register. That name must be unique within each registering type. Dependency 
properties inherited through base types are considered to be already part of the registering type; names of 
inherited properties cannot be registered again. However, there is a technique for adding a class as owner of a 
dependency property even when that dependency property is not inherited; for details, see Dependency 
Property Metadata. 

When you create the identifier field, name this field by the name of the property as you registered it, plus the 
suffix Property . This field is your identifier for the dependency property, and it will be used later as an input 
for the SetValue and GetValue calls you will make in the wrappers, by any other code access to the property by 
your own code, by any external code access you allow, by the property system, and potentially by XAML 
processors. 


NOTE 

Defining the dependency property in the class body is the typical implementation, but it is also possible to define a 
dependency property in the class static constructor. This approach might make sense if you need more than one line of 
code to initialize the dependency property. 


Implementing the "Wrapper" 

Your wrapper implementation should call GetValue in the get implementation, and SetValue in the set 
implementation (the original registration call and field are shown here too for clarity). 

In all but exceptional circumstances, your wrapper implementations should perform only the GetValue and 
SetValue actions, respectively. The reason for this is discussed in the topic XAML Loading and Dependency 
Properties. 







All existing public dependency properties that are provided on the WPF classes use this simple wrapper 
implementation model; most of the complexity of how dependency properties work is either inherently a 
behavior of the property system, or is implemented through other concepts such as coercion or property 
change callbacks through property metadata. 

public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register( 
"AquariumGraphic"j 
typeof(Uri)j 
typeof(AquariumObject), 
new FrameworkPropertyMetadata(null, 

FrameworkPropertyMetadataOptions.AffectsRendeCj 
new PropertyChangedCallback(OnUriCbanged) 

) 

); 

public Uri AquariumGraphic 

{ 

get { return (Uri)GetValue(AquariumGraphicProperty); } 
set { SetValue(AquariumGraphicPropertyj value); } 

} 


Public Shared Readonly AquariumGraphicProperty As DependencyProperty = 

DependencyProperty.Register("AquariumGraphic"j GetType(Llri), GetType(AquariumObject)j New 
FrameworkPropertyMetadata(Nothingj FrameworkPropertyMetadataOptions.AffectsRender, New 
PropertyChangedCallback(AddressOf OnUriChanged))) 

Public Property AquariumGraphic() As Uri 
Get 

Return CType(GetValue(AquariumGraphicProperty)j Uri) 

End Get 

Set(ByVal value As Uri) 

SetValue(AquariumGraphicPropertyj value) 

End Set 
End Property 


Again, by convention, the name of the wrapper property must be the same as the name chosen and given as 
first parameter of the Register call that registered the property. If your property does not follow the 
convention, this does not necessarily disable all possible uses, but you will encounter several notable issues: 

• Certain aspects of styles and templates will not work. 

• Most tools and designers must rely on the naming conventions to properly serialize XAML, or to 
provide designer environment assistance at a per-property level. 

• The current implementation of the WPF XAML loader bypasses the wrappers entirely, and relies on the 
naming convention when processing attribute values. For more information, see XAML Loading and 
Dependency Properties. 

Property Metadata fora New Dependency Property 

When you register a dependency property, the registration through the property system creates a metadata 
object that stores property characteristics. Many of these characteristics have defaults that are set if the 
property is registered with the simple signatures of Register. Other signatures of Register allow you to specify 
the metadata that you want as you register the property. The most common metadata given for dependency 
properties is to give them a default value that is applied on new instances that use the property. 

If you are creating a dependency property that exists on a derived class of FrameworkElement, you can use 
the more specialized metadata class FrameworkPropertyMetadata rather than the base PropertyMetadata 
class. The constructor for the FrameworkPropertyMetadata class has several signatures where you can specify 
various metadata characteristics in combination. If you want to specify the default value only, use the 



signature that takes a single parameter of type Object. Pass that object parameter as a type-specific default 
value for your property (the default value provided must be the type you provided as the property Type 
parameter in the Register call). 

For FrameworkPropertyMetadata, you can also specify metadata option flags for your property. These flags 
are converted into discrete properties on the property metadata after registration and are used to 
communicate certain conditionals to other processes such as the layout engine. 

Setting Appropriate Metadata Flags 

• If your property (or changes in its value) affects the user interface (Ul), and in particular affects how the 
layout system should size or render your element in a page, set one or more of the following flags: 
AffectsMeasure, AffectsArrange, AffectsRender. 

o AffectsMeasure indicates that a change to this property requires a change to Ul rendering where 
the containing object might require more or less space within the parent. For example, a "Width" 
property should have this flag set. 

o AffectsArrange indicates that a change to this property requires a change to Ul rendering that 
typically does not require a change in the dedicated space, but does indicate that the positioning 
within the space has changed. For example, an "Alignment" property should have this flag set. 

o AffectsRender indicates that some other change has occurred that will not affect layout and 
measure, but does require another render. An example would be a property that changes a color 
of an existing element, such as "Background". 

o These flags are often used as a protocol in metadata for your own override implementations of 
property system or layout callbacks. For instance, you might have an OnPropertyChanged 
callback that will call InvalidateArrange if any property of the instance reports a value change 
and has AffectsArrange as true in its metadata. 

• Some properties may affect the rendering characteristics of the containing parent element, in ways 
above and beyond the changes in required size mentioned above. An example is the MinOrphanLines 
property used in the flow document model, where changes to that property can change the overall 
rendering of the flow document that contains the paragraph. Use Affects Pa rentArrange or 
AffectsParentMeasure to identify similar cases in your own properties. 

• By default, dependency properties support data binding. You can deliberately disable data binding, for 
cases where there is no realistic scenario for data binding, or where performance in data binding for a 
large object is recognized as a problem. 

• By default, data binding Mode for dependency properties defaults to OneWay. You can always change 
the binding to be TwoWay per binding instance; for details, see Specify the Direction of the Binding. But 
as the dependency property author, you can choose to make the property use TwoWay binding mode 
by default. An example of an existing dependency property is Menultem.lsSubmenuOpen; the scenario 
for this property is that the IsSubmenuOpen setting logic and the compositing of Menultem interact 
with the default theme style. The IsSubmenuOpen property logic uses data binding natively to maintain 
the state of the property in accordance to other state properties and method calls. Another example 
property that binds TwoWay by default is TextBox.Text. 

• You can also enable property inheritance in a custom dependency property by setting the Inherits flag. 
Property inheritance is useful for a scenario where parent elements and child elements have a property 
in common, and it makes sense for the child elements to have that particular property value set to the 
same value as the parent set it. An example inheritable property is DataContext, which is used for 
binding operations to enable the important master-detail scenario for data presentation. By making 
DataContext inheritable, any child elements inherit that data context also. Because of property value 
inheritance, you can specify a data context at the page or application root, and do not need to respecify 




it for bindings in all possible child elements. DataContext is also a good example to illustrate that 
inheritance overrides the default value, but it can always be set locally on any particular child element; 
for details, see Use the Master-Detail Pattern with Hierarchical Data. Property value inheritance does 
have a possible performance cost, and thus should be used sparingly; for details, see Property Value 
Inheritance. 

• Set the Journal flag to indicate if your dependency property should be detected or used by navigation 
journaling services. An example is the Selectedindex property; any item selected in a selection control 
should be persisted when thejournaling history is navigated. 

Read-Only Dependency Properties 

You can define a dependency property that is read-only. However, the scenarios for why you might define your 
property as read-only are somewhat different, as is the procedure for registering them with the property 
system and exposing the identifier. For more information, see Read-Only Dependency Properties. 

Collection-Type Dependency Properties 

Collection-type dependency properties have some additional implementation issues to consider. For details, 
see Collection-Type Dependency Properties. 

Dependency Property Security Considerations 

Dependency properties should be declared as public properties. Dependency property identifier fields should 
be declared as public static fields. Even if you attempt to declare other access levels (such as protected), a 
dependency property can always be accessed through the identifier in combination with the property system 
APIs. Even a protected identifier field is potentially accessible because of metadata reporting or value 
determination APIs that are part of the property system, such as LocalValueEnumerator. For more 
information, see Dependency Property Security. 

Dependency Properties and Class Constructors 

There is a general principle in managed code programming (often enforced by code analysis tools such as 
FxCop) that class constructors should not call virtual methods. This is because constructors can be called as 
base initialization of a derived class constructor, and entering the virtual method through the constructor 
might occur at an incomplete initialization state of the object instance being constructed. When you derive 
from any class that already derives from DependencyObject, you should be aware that the property system 
itself calls and exposes virtual methods internally. These virtual methods are part of the WPF property system 
services. Overriding the methods enables derived classes to participate in value determination. To avoid 
potential issues with runtime initialization, you should not set dependency property values within constructors 
of classes, unless you follow a very specific constructor pattern. For details, see Safe Constructor Patterns for 
DependencyObjects. 

See also 

• Dependency Properties Overview 

• Dependency Property Metadata 

• Control Authoring Overview 

• Collection-Type Dependency Properties 

• Dependency Property Security 

• XAML Loading and Dependency Properties 

• Safe Constructor Patterns for DependencyObjects 
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The Windows Presentation Foundation (WPF) property system includes a metadata reporting system that goes 
beyond what can be reported about a property through reflection or general common language runtime (CLR) 
characteristics. Metadata for a dependency property can also be assigned uniquely by the class that defines a 
dependency property, can be changed when the dependency property is added to a different class, and can be 
specifically overridden by all derived classes that inherit the dependency property from the defining base class. 

Prerequisites 

This topic assumes that you understand dependency properties from the perspective of a consumer of existing 
dependency properties on Windows Presentation Foundation (WPF) classes, and have read the Dependency 
Properties Overview. In order to follow the examples in this topic, you should also understand XAML and know 
how to write WPF applications. 

How Dependency Property Metadata is Used 

Dependency property metadata exists as an object that can be queried to examine the characteristics of a 
dependency property. This metadata is also accessed frequently by the property system as it processes any given 
dependency property. The metadata object for a dependency property can contain the following types of 
information: 

• Default value for the dependency property, if no other value can be determined for the dependency 
property by local value, style, inheritance, etc. For a thorough discussion of how default values participate 
in the precedence used by the property system when assigning values for dependency properties, see 
Dependency Property Value Precedence. 

• References to callback implementations that affect coercion or change-notification behaviors on a per- 
owner-type basis. Note that these callbacks are often defined with a nonpublic access level, so obtaining 
the actual references from metadata is generally not possible unless the references are within your 
permitted access scope. For more information on dependency property callbacks, see Dependency 
Property Callbacks and Validation. 

• If the dependency property in question is considered to be a WPF framework-level property, the metadata 
might contain WPF framework-level dependency property characteristics, which report information and 
state for services such as the WPF framework-level layout engine and property inheritance logic. For 
more information on this aspect of dependency property metadata, see Framework Property Metadata. 

Metadata APIs 

The type that reports most of the metadata information used by the property system is the PropertyMetadata 
class. Metadata instances are optionally specified when dependency properties are registered with the property 
system, and can be specified again for additional types that either add themselves as owners or override 
metadata they inherit from the base class dependency property definition. (For cases where a property 
registration does not specify metadata, a default PropertyMetadata is created with default values for that 
class.)The registered metadata is returned as PropertyMetadata when you call the various GetMetadata 
overloads that get metadata from a dependency property on a DependencyObject instance. 

The PropertyMetadata class is then derived from to provide more specific metadata for architectural divisions 
such as the WPF framework-level classes. UI PropertyMetadata adds animation reporting, and 




FrameworkPropertyMetadata provides the WPF framework-level properties mentioned in the previous section. 
When dependency properties are registered, they can be registered with these PropertyMetadata derived 
classes. When the metadata is examined, the base PropertyMetadata type can potentially be cast to the derived 
classes so that you can examine the more specific properties. 


NOTE 

The property characteristics that can be specified in FrameworkPropertyMetadata are sometimes referred to in this 
documentation as "flags". When you create new metadata instances for use in dependency property registrations or 
metadata overrides, you specify these values using the flagwise enumeration FrameworkPropertyMetadataOptions and 
then you supply possibly concatenated values of the enumeration to the FrameworkPropertyMetadata constructor. 
However, once constructed, these option characteristics are exposed within a FrameworkPropertyMetadata as a series of 
Boolean properties rather than the constructing enumeration value. The Boolean properties enable you to check each 
conditional, rather than requiring you to apply a mask to a flagwise enumeration value to get the information you are 
interested in. The constructor uses the concatenated FrameworkPropertyMetadataOptions in order to keep the length of 
the constructor signature reasonable, whereas the actual constructed metadata exposes the discrete properties to make 
querying the metadata more intuitive. 


When to Override Metadata, When to Derive a Class 

The WPF property system has established capabilities for changing some characteristics of dependency 
properties without requiring them to be entirely re-implemented. This is accomplished by constructing a 
different instance of property metadata for the dependency property as it exists on a particular type. Note that 
most existing dependency properties are not virtual properties, so strictly speaking "re-implementing" them on 
inherited classes could only be accomplished by shadowing the existing member. 

If the scenario you are trying to enable for a dependency property on a type cannot be accomplished by 
modifying characteristics of existing dependency properties, it might then be necessary to create a derived class, 
and then to declare a custom dependency property on your derived class. A custom dependency property 
behaves identically to dependency properties defined by the WPF APIs. For more details about custom 
dependency properties, see Custom Dependency Properties. 

One notable characteristic of a dependency property that you cannot override is its value type. If you are 
inheriting a dependency property that has the approximate behavior you require, but you require a different 
type for it, you will have to implement a custom dependency property and perhaps link the properties through 
type conversion or other implementation on your custom class. Also, you cannot replace an existing 
ValidateValueCallback, because this callback exists in the registration field itself and not within its metadata. 

Scenarios for Changing Existing Metadata 

If you are working with metadata of an existing dependency property, one common scenario for changing 
dependency property metadata is to change the default value. Changing or adding property system callbacks is 
a more advanced scenario. You might want to do this if your implementation of a derived class has different 
interrelationships between dependency properties. One of the conditionals of having a programming model that 
supports both code and declarative usage is that properties must enable being set in any order. Thus any 
dependent properties need to be set just-in-time without context and cannot rely on knowing a setting order 
such as might be found in a constructor. For more information on this aspect of the property system, see 
Dependency Property Callbacks and Validation. Note that validation callbacks are not part of the metadata; they 
are part of the dependency property identifier. Therefore, validation callbacks cannot be changed by overriding 
the metadata. 

In some cases you might also want to alter the WPF framework-level property metadata options on existing 
dependency properties. These options communicate certain known conditionals about WPF framework-level 
properties to other WPF framework-level processes such as the layout system. Setting the options is generally 



done only when registering a new dependency property, but it is also possible to change the WPF frannework- 
level property metadata as part of a OverrideMetadata or AddOwner call. For the specific values to use and more 
information, see Framework Property Metadata. For more information that is pertinent to how these options 
should be set for a newly registered dependency property, see Custom Dependency Properties. 

Overriding Metadata 

The purpose of overriding metadata is primarily so that you have the opportunity to change the various 
metadata-derived behaviors that are applied to the dependency property as it exists on your type. The reasons 
for this are explained in more detail in the Metadata section. For more information including some code 
examples, see Override Metadata for a Dependency Property. 

Property metadata can be supplied for a dependency property during the registration call (Register). However, in 
many cases, you might want to provide type-specific metadata for your class when it inherits that dependency 
property. You can do this by calling the OverrideMetadata method. For an example from the WPF APIs, the 
FrameworkElement class is the type that first registers the Focusable dependency property. But the Control class 
overrides metadata for the dependency property to provide its own initial default value, changing it from false 
to true , and otherwise re-uses the original Focusable implementation. 

When you override metadata, the different metadata characteristics are either merged or replaced. 

• PropertyChangedCallback is merged. If you add a new PropertyChangedCallback, that callback is stored 
in the metadata. If you do not specify a PropertyChangedCallback in the override, the value of 
PropertyChangedCallback is promoted as a reference from the nearest ancestor that specified it in 
metadata. 

• The actual property system behavior for PropertyChangedCallback is that implementations for all 
metadata owners in the hierarchy are retained and added to a table, with order of execution by the 
property system being that the most derived class's callbacks are invoked first. 

• DefauItValue is replaced. If you do not specify a DefauItValue in the override, the value of DefauItValue 
comes from the nearest ancestor that specified it in metadata. 

• CoerceValueCallback implementations are replaced. If you add a new CoerceValueCallback, that callback is 
stored in the metadata. If you do not specify a CoerceValueCallback in the override, the value of 
CoerceValueCallback is promoted as a reference from the nearest ancestor that specified it in metadata. 

• The property system behavior is that only the CoerceValueCallback in the immediate metadata is invoked. 

No references to other CoerceValueCallback implementations in the hierarchy are retained. 

This behavior is implemented by Merge, and can be overridden on derived metadata classes. 

Overriding Attached Property Metadata 

In WPF, attached properties are implemented as dependency properties. This means that they also have property 
metadata, which individual classes can override. The scoping considerations for an attached property in WPF are 
generally that any DependencyObject can have an attached property set on them. Therefore, any 
DependencyObject derived class can override the metadata for any attached property, as it might be set on an 
instance of the class. You can override default values, callbacks, or WPF framework-level characteristic-reporting 
properties. If the attached property is set on an instance of your class, those override property metadata 
characteristics apply. For instance, you can override the default value, such that your override value is reported 
as the value of the attached property on instances of your class, whenever the property is not otherwise set. 


NOTE 

The Inherits property is not relevant for attached properties. 


Adding a Class as an Owner of an Existing Dependency Property 





A class can add itself as an owner of a dependency property that has already been registered, by using the 
AddOwner method. This enables the class to use a dependency property that was originally registered for a 
different type. The adding class is typically not a derived class of the type that first registered that dependency 
property as owner. Effectively, this allows your class and its derived classes to "inherit" a dependency property 
implementation without the original owner class and the adding class being in the same true class hierarchy. In 
addition, the adding class (and all derived classes as well) can then provide type-specific metadata for the 
original dependency property. 

As well as adding itself as owner through the property system utility methods, the adding class should declare 
additional public members on itself in order to make the dependency property] a full participant in the property 
system with exposure to both code and markup. A class that adds an existing dependency property has the same 
responsibilities as far as exposing the object model for that dependency property as does a class that defines a 
new custom dependency property. The first such member to expose is a dependency property identifier field. 
This field should be a public static readonly field of type DependencyProperty, which is assigned to the return 
value of the AddOwner call. The second member to define is the common language runtime (CLR) "wrapper" 
property. The wrapper makes it much more convenient to manipulate your dependency property in code (you 
avoid calls to SetValue each time, and can make that call only once in the wrapper itself). The wrapper is 
implemented identically to how it would be implemented if you were registering a custom dependency property. 
For more information about implementing a dependency property, see Custom Dependency Properties and Add 
an Owner Type for a Dependency Property. 

AddOwner and Attached Properties 

You can call AddOwner for a dependency property that is defined as an attached property by the owner class. 
Generally the reason for doing this is to expose the previously attached property as a non-attached dependency 
property. You then will expose the AddOwner return value as a public static readonly field for use as the 
dependency property identifier, and will define appropriate "wrapper" properties so that the property appears in 
the members table and supports a non-attached property usage in your class. 

See also 

• PropertyMetadata 

• DependencyObJect 

• DependencyProperty 

• GetMetadata 

• Dependency Properties Overview 

• Framework Property Metadata 
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This topic describes how to create dependency properties using alternative custom implementations for 
property-related features such as validation determination, callbacks that are invoked whenever the property's 
effective value is changed, and overriding possible outside influences on value determination. This topic also 
discusses scenarios where expanding on the default property system behaviors by using these techniques is 
appropriate. 

Prerequisites 

This topic assumes that you understand the basic scenarios of implementing a dependency property, and how 
metadata is applied to a custom dependency property. See Custom Dependency Properties and Dependency 
Property Metadata for context. 

Validation Callbacks 

Validation callbacks can be assigned to a dependency property when you first register it. The validation callback is 
not part of property metadata; it is a direct input of the Register method. Therefore, once a validation callback is 
created for a dependency property, it cannot be overridden by a new implementation. 

public static readonly DependencyProperty CurrentReadingProperty = DependencyProperty.Register( 

"CurrentReading", 
typeof(double), 
typeof(Gauge), 

new FrameworkPropertyMetadata( 

Double. NalM, 

FrameworkPropertyMetadataOptions.AffectsMeasure, 
new PropertyChangedCallback(OnCurrentReadingChanged), 
new CoerceValueCallback(CoerceCurrentReading) 

). 

new ValidateValueCallback(IsValidReading) 

); 

public double CurrentReading 
{ 

get { return (double)GetValue(CurrentReadingProperty); } 
set { SetValue(CurrentReadingProperty, value); } 

} 





Public Shared Readonly CurrentReadingProperty As DependencyProperty = 

DependencyProperty.Register("CurrentReading"j 
GetType(Double)j GetType(Gauge)j 
New FrameworkPropertyMetadata(Double.NaNj 

FrameworkPropertyMetadataOptions.AffectsMeasure, 

New PropertyChangedCallback(AddressOf OnCurrentReadingChanged)j 
New Coerce\/alueCallback(AddressOf CoerceCurrentReading))j 
New \/alidate\/alueCallback(AddressOf IsValidReading)) 

Public Property CurrentReadingO As Double 
Get 

Return CDbl(GetValue(CurrentReadingProperty)) 

End Get 

Set(By\/al value As Double) 

SetValue(CurrentReadingPropertyj value) 

End Set 
End Property 

The callbacks are implemented such that they are provided an object value. They return true if the provided 
value is valid for the property; otherwise, they return false . It is assumed that the property is of the correct type 
per the type registered with the property system, so checking type within the callbacks is not ordinarily done. The 
callbacks are used by the property system in a variety of different operations. This includes the initial type 
initialization by default value, programmatic change by invoking SetValue, or attempts to override metadata with 
new default value provided. If the validation callback is invoked by any of these operations, and returns false , 
then an exception will be raised. Application writers must be prepared to handle these exceptions. A common use 
of validation callbacks is validating enumeration values, or constraining values of integers or doubles when the 
property sets measurements that must be zero or greater. 

Validation callbacks specifically are intended to be class validators, not instance validators. The parameters of the 
callback do not communicate a specific DependencyObJect on which the properties to validate are set. Therefore 
the validation callbacks are not useful for enforcing the possible "dependencies" that might influence a property 
value, where the instance-specific value of a property is dependent on factors such as instance-specific values of 
other properties, or run-time state. 

The following is example code for a very simple validation callback scenario: validating that a property that is 
typed as the Double primitive is not Positiveinfinity or Negativeinfinity. 

public static bool IsValidReading(object value) 

{ 

Double V = (Double)value; 

return (!v.Equals(Double.Negativeinfinity) && !v.Equals(Double.Positiveinfinity)); 

} 


Public Shared function IsValidReading(ByVal value As Object) As Boolean 
Dim V As Double = CType(valuej Double) 

Return ((Not v.Equals(Double.Negativeinfinity)) AndAlso 
(Not V. Equals(Double.Positiveinfinity))) 

End function 


Coerce Value Callbacks and Property Changed Events 

Coerce value callbacks do pass the specific DependencyObJect instance for properties, as do 
PropertyChangedCallback implementations that are invoked by the property system whenever the value of a 
dependency property changes. Using these two callbacks in combination, you can create a series of properties on 
elements where changes in one property will force a coercion or reevaluation of another property. 






A typical scenario for using a linkage of dependency properties is when you have a user interface driven property 
where the element holds one property each for the minimum and maximum value, and a third property for the 
actual or current value. Here, if the maximum was adjusted in such a way that the current value exceeded the new 
maximum, you would want to coerce the current value to be no greater than the new maximum, and a similar 
relationship for minimum to current. 

The following is very brief example code for just one of the three dependency properties that illustrate this 
relationship. The example shows how the currentReading property of a Min/Max/Current set of related *Reading 
properties is registered. It uses the validation as shown in the previous section. 

public static readonly DependencyProperty CurrentReadingProperty = DependencyProperty.Register( 
"CurrentReading", 
typeof(double), 
typeof(Gauge), 

new FrameworkPropertyMetadata( 

Double. NalM, 

FrameworkPropertyMetadataOptions.AffectsMeasure, 
new PropertyChangedCallback(OnCurrentReadingChanged), 
new CoerceValueCallback(CoerceCurrentReading) 

). 

new ValidateValueCallback(IsValidReading) 

); 

public double CurrentReading 

{ 

get { return (double)GetValue(CurrentReadingProperty); } 
set { SetValue(CurrentReadingProperty, value); } 

} 


Public Shared Readonly CurrentReadingProperty As DependencyProperty = 
DependencyProperty.Register("CurrentReading", 

GetType(Double), GetType(Gauge), 

New FrameworkPropertyMetadata(Double.NaN, 

FrameworkPropertyMetadataOptions.AffectsMeasure, 

New PropertyChangedCallback(AddressOf OnCurrentReadingChanged), 
New CoerceValueCallback(AddressOf CoerceCurrentReading)), 

New ValidateValueCallback(AddressOf IsValidReading)) 

Public Property CurrentReadingO As Double 
Get 

Return CDbl(GetValue(CurrentReadingProperty)) 

End Get 

Set(ByVal value As Double) 

SetValue(CurrentReadingProperty, value) 

End Set 
End Property 


The property changed callback for Current is used to forward the change to other dependent properties, by 
explicitly invoking the coerce value callbacks that are registered for those other properties: 

private static void OnCurrentReadingChanged(DependencyObject d, DependencyPropertyChangedEventArgs e) 

{ 

d. CoerceValue(MinReadingProperty); 
d.CoerceValue(MaxReadingProperty); 

} 




Private Shared Sub OnCurrentReadingChanged(ByVal d As DependencyObjectj ByVal e As 
DependencyPropertyChangedEventArgs) 
d .Coerce\/alue(MinReadingProperty) 
d .Coerce\/alue(MaxReadingProperty) 

End Sub 


The coerce value callback checks the values of properties that the current property is potentially dependent upon, 
and coerces the current value if necessary: 

private static object CoerceCurrentReading(DependencyObject d, object value) 

{ 

Gauge g = (Gauge)d; 

double current = (double)value; 

if (current < g.MinReading) current = g.MinReading; 
if (current > g.MaxReading) current = g.MaxReading; 
return current; 


Private Shared Function CoerceCurrentReading(ByVal d As DependencyObjectj ByVal value As Object) As Object 
Dim g As Gauge = CType(d, Gauge) 

Dim current As Double = CDbl(value) 

If current < g.MinReading Then 
current = g.MinReading 
End If 

If current > g.MaxReading Then 
current = g.MaxReading 
End If 

Return current 
End Function 


NOTE 

Default values of properties are not coerced. A property value equal to the default value might occur if a property value still 
has its initial default, or through clearing other values with ClearValue. 


The coerce value and property changed callbacks are part of property metadata. Therefore, you can change the 
callbacks for a particular dependency property as it exists on a type that you derive from the type that owns the 
dependency property, by overriding the metadata for that property on your type. 

Advanced Coercion and Callback Scenarios 

Constraints and Desired Values 

The CoerceValueCallback callbacks will be used by the property system to coerce a value in accordance to the 
logic you declare, but a coerced value of a locally set property will still retain a "desired value" internally. If the 
constraints are based on other property values that may change dynamically during the application lifetime, the 
coercion constraints are changed dynamically also, and the constrained property can change its value to get as 
close to the desired value as possible given the new constraints. The value will become the desired value if all 
constraints are lifted. You can potentially introduce some fairly complicated dependency scenarios if you have 
multiple properties that are dependent on one another in a circular manner. For instance, in the Min/Max/Current 
scenario, you could choose to have Minimum and Maximum be user settable. If so, you might need to coerce that 
Maximum is always greater than Minimum and vice versa. But if that coercion is active, and Maximum coerces to 
Minimum, it leaves Current in an unsettable state, because it is dependent on both and is constrained to the range 
between the values, which is zero. Then, if Maximum or Minimum are adjusted. Current will seem to "follow" one 
of the values, because the desired value of Current is still stored and is attempting to reach the desired value as 





the constraints are loosened. 


There is nothing technically wrong with complex dependencies, but they can be a slight performance detriment if 
they require large numbers of reevaluations, and can also be confusing to users if they affect the Ul directly. Be 
careful with property changed and coerce value callbacks and make sure that the coercion being attempted can 
be treated as unambiguously as possible, and does not "overconstrain". 

Using CoerceValue to Cancel Value Changes 

The property system will treat any CoerceValueCallback that returns the value UnsetValue as a special case. This 
special case means that the property change that resulted in the CoerceValueCallback being called should be 
rejected by the property system, and that the property system should instead report whatever previous value the 
property had. This mechanism can be useful to check that changes to a property that were initiated 
asynchronously are still valid for the current object state, and suppress the changes if not. Another possible 
scenario is that you can selectively suppress a value depending on which component of property value 
determination is responsible for the value being reported. To do this, you can use the DependencyProperty 
passed in the callback and the property identifier as input for GetValueSource, and then process the ValueSource. 

See also 

• Dependency Properties Overview 

• Dependency Property Metadata 

• Custom Dependency Properties 


Framework Property Metadata 

3/12/2020 • 5 minutes to read ^ Edit Online 


Framework property metadata options are reported for the properties of object elements considered to be at the 
WPF framework level in the Windows Presentation Foundation (WPF) architecture. In general the WPF 
framework-level designation entails that features such as rendering, data binding, and property system 
refinements are handled by the WPF presentation APIs and executables. Framework property metadata is queried 
by these systems to determine feature-specific characteristics of particular element properties. 

Prerequisites 

This topic assumes that you understand dependency properties from the perspective of a consumer of existing 
dependency properties on Windows Presentation Foundation (WPF) classes, and have read the Dependency 
Properties Overview. You should also have read Dependency Property Metadata. 

What Is Communicated by Framework Property Metadata 

Framework property metadata can be divided into the following categories: 

• Reporting layout properties that affect an element (AffectsArrange, AffectsMeasure, AffectsRender). You 
might set these flags in metadata if the property affects those respective aspects, and you are also 
implementing the MeasureOverride / ArrangeOverride methods in your class to supply specific rendering 
behavior and information to the layout system. Typically, such an implementation would check for property 
invalidations in dependency properties where any of these layout properties were true in the property 
metadata, and only those invalidations would necessitate requesting a new layout pass. 

• Reporting layout properties that affect the parent element of an element (AffectsParentArrange, 
AffectsParentMeasure). Some examples where these flags are set by default are FixedPage.Left and 
Paragraph.KeepWithNext. 

• Inherits. By default, dependency properties do not inherit values. OverridesInheritanceBehavior allows the 
pathway of inheritance to also travel into a visual tree, which is necessary for some control compositing 
scenarios. 


NOTE 

The term "inherits" in the context of property values means something specific for dependency properties; it means 
that child elements can inherit the actual dependency property value from parent elements because of a WPF 
framework-level capability of the WPF property system. It has nothing to do directly with managed code type and 
members inheritance through derived types. For details, see Property Value Inheritance. 


• Reporting data binding characteristics (IsNotDataBindable, BindsTwoWayByDefault). By default, 
dependency properties in the framework support data binding, with a one-way binding behavior. You 
might disable data binding if there were no scenario for it whatsoever (because they are intended to be 
flexible and extensible, there aren't many examples of such properties in the default WPF APIs). You might 
set binding to have a two-way default for properties that tie together a control's behaviors amongst its 
component pieces (IsSubmenuOpen is an example) or where two-way binding is the common and 
expected scenario for users (Text is an example). Changing the data binding-related metadata only 
influences the default; on a per-binding basis that default can always be changed. For details on the binding 
modes and binding in general, see Data Binding Overview. 





• Reporting whether properties should be journaled by applications or services that support journaling 
(Journal). For general elements, journaling is not enabled by default, but it is selectively enabled for certain 
user input controls. This property is intended to be read by journaling services including the WPF 
implementation of journaling, and is typically set on user controls such as user selections within lists that 
should be persisted across navigation steps. For information about the journal, see Navigation Overview. 

Reading FrameworkPropertyMetadata 

Each of the properties linked above are the specific properties that the FrameworkPropertyMetadata adds to its 
immediate base class UI Property Metadata. Each of these properties will be false by default. A metadata request 
for a property where knowing the value of these properties is important should attempt to cast the returned 
metadata to FrameworkPropertyMetadata, and then check the values of the individual properties as needed. 

Specifying Metadata 

When you create a new metadata instance for purposes of applying metadata to a new dependency property 
registration, you have the choice of which metadata class to use: the base PropertyMetadata or some derived 
class such as FrameworkPropertyMetadata. In general, you should use FrameworkPropertyMetadata, particularly 
if your property has any interaction with property system and WPF functions such as layout and data binding. 
Another option for more sophisticated scenarios is to derive from FrameworkPropertyMetadata to create your 
own metadata reporting class with extra information carried in its members. Or you might use PropertyMetadata 
or UI PropertyMetadata to communicate the degree of support for features of your implementation. 

For existing properties (AddOwner or OverrideMetadata call), you should always override with the metadata type 
used by the original registration. 

If you are creating a FrameworkPropertyMetadata instance, there are two ways to populate that metadata with 
values for the specific properties that communicate the framework property characteristics: 

1. Use the FrameworkPropertyMetadata constructor signature that allows a flags parameter. This 
parameter should be filled with all desired combined values of the FrameworkPropertyMetadataOptions 
enumeration flags. 

2. Use one of the signatures without a flags parameter, and then set each reporting Boolean property on 
FrameworkPropertyMetadata to true for each desired characteristic change. If you do this, you must set 
these properties before any elements with this dependency property are constructed; the Boolean 
properties are read-write in order to allow this behavior of avoiding the flags parameter and still 
populate the metadata, but the metadata must become effectively sealed before property use. Thus, 
attempting to set the properties after metadata is requested will be an invalid operation. 

Framework Property Metadata Merge Behavior 

When you override framework property metadata, the different metadata characteristics are either merged or 
replaced. 

• PropertyChangedCallback is merged. If you add a new PropertyChangedCallback, that callback is stored in 
the metadata. If you do not specify a PropertyChangedCallback in the override, the value of 
PropertyChangedCallback is promoted as a reference from the nearest ancestor that specified it in 
metadata. 

• The actual property system behavior for PropertyChangedCallback is that implementations for all 
metadata owners in the hierarchy are retained and added to a table, with order of execution by the 
property system being that the callbacks of the most deeply derived class are invoked first. Inherited 
callbacks run only once, counting as being owned by the class that placed them in metadata. 






• DefauItValue is replaced. If you do not specify a PropertyChangedCallback in the override, the value of 
DefauItValue comes from the nearest ancestor that specified it in metadata. 

• CoerceValueCallback implementations are replaced. If you add a new CoerceValueCallback, that callback is 
stored in the metadata. If you do not specify a CoerceValueCallback in the override, the value of 
CoerceValueCallback is promoted as a reference from the nearest ancestor that specified it in metadata. 

• The property system behavior is that only the CoerceValueCallback in the immediate metadata is invoked. 
No references to other CoerceValueCallback implementations in the hierarchy are retained. 

• The flags of FrameworkPropertyMetadataOptions enumeration are combined as a bitwise OR operation. If 
you specify FrameworkPropertyMetadataOptions, the original options are not overwritten. To change an 
option, set the corresponding property on FrameworkPropertyMetadata. For example, if the original 
FrameworkPropertyMetadata object sets the FrameworkPropertyMetadataOptions.NotDataBindable flag, 
you can change that by setting FrameworkPropertyMetadata.IsNotDataBindable to false . 

This behavior is implemented by Merge, and can be overridden on derived metadata classes. 

See also 

• GetMetadata 

• Dependency Property Metadata 

• Dependency Properties Overview 

• Custom Dependency Properties 



Dependency Property Value Precedence 
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This topic explains how the workings of the Windows Presentation Foundation (WPF) property system can affect 
the value of a dependency property, and describes the precedence by which aspects of the property system apply 
to the effective value of a property. 

Prerequisites 

This topic assumes that you understand dependency properties from the perspective of a consumer of existing 
dependency properties on WPF classes, and have read Dependency Properties Overview. To follow the examples 
in this topic, you should also understand Extensible Application Markup Language (XAML) and know how to write 
WPF applications. 

The WPF Property System 

The WPF property system offers a powerful way to have the value of dependency properties be determined by a 
variety of factors, enabling features such as real-time property validation, late binding, and notifying related 
properties of changes to values for other properties. The exact order and logic that is used to determine 
dependency property values is reasonably complex. Knowing this order will help you avoid unnecessary 
property setting, and might also clear up confusion over exactly why some attempt to influence or anticipate a 
dependency property value did not end up resulting in the value you expected. 

Dependency Properties Might Be "Set" in Multiple Places 

The following is example XAML where the same property (Background) has three different "set" operations that 
might influence the value. 

<Button Bacl<gr'ound="Red"> 

<Button.Style> 

<Style Tar'getType="{x:Type Button}"> 

<Setter Property="Backgr'ound" Value="Green"/> 

<Style.Triggers> 

<Trigger Property="IsMouseOver" Value="True"> 

<Setter Property="Background" Value="Blue" /> 

</Trigger> 

</Style.Triggers> 

</Style> 

</Button.Styles 

Click 

</Button> 


Here, which color do you expect will apply—red, green, or blue? 

With the exception of animated values and coercion, local property sets are set at the highest precedence. If you 
set a value locally you can expect that the value will be honored, even above any styles or control templates. Here 
in the example. Background is set to Red locally. Therefore, the style defined in this scope, even though it is an 
implicit style that would otherwise apply to all elements of that type in that scope, is not the highest precedence 
for giving the Background property its value. If you removed the local value of Red from that Button instance, 
then the style would have precedence and the button would obtain the Background value from the style. Within 
the style, triggers take precedence, so the button will be blue if the mouse is over it, and green otherwise. 





Dependency Property Setting Precedence List 

The following is the definitive order that the property system uses when assigning the run-time values of 

dependency properties. Highest precedence is listed first. This list expands on some of the generalizations made 

in the Dependency Properties Overview. 

1. Property system coercion. For details on coercion, see Coercion, Animation, and Base Value later in this 
topic. 

2. Active animations, or animations with a Hold behavior. In order to have any practical effect, an 
animation of a property must be able to have precedence over the base (unanimated) value, even if that 
value was set locally. For details, see Coercion, Animation, and Base Value later in this topic. 

3. Local value. A local value might be set through the convenience of the "wrapper" property, which also 
equates to setting as an attribute or property element in XAML, or by a call to the SetValue API using a 
property of a specific instance. If you set a local value by using a binding or a resource, these each act in 
the precedence as if a direct value was set. 

4. Templated Parent template properties. An element has a Tern plated Pa rent if it was created as part of a 
template (a ControlTemplate or Data Template). For details on when this applies, see TemplatedParent later 
in this topic. Within the template, the following precedence applies: 

a. Triggers from the TemplatedParent template. 

b. Property sets (typically through XAML attributes) in the TemplatedParent template. 

5. Implicit style. Applies only to the style property. The style property is filled by any style resource 
with a key that matches the type of that element. That style resource must exist either in the page or the 
application; lookup for an implicit style resource does not proceed into the themes. 

6. Style triggers. The triggers within styles from page or application (these styles might be either explicit or 
implicit styles, but not from the default styles, which have lower precedence). 

7. Template triggers. Any trigger from a template within a style, or a directly applied template. 

8. Style setters. Values from a Setter within styles from page or application. 

9. Default (theme) style. For details on when this applies, and how theme styles relate to the templates 
within theme styles, see Default (Theme) Styles later in this topic. Within a default style, the following order 
of precedence applies: 

a. Active triggers in the theme style. 

b. Setters in the theme style. 

10. Inheritance. A few dependency properties inherit their values from parent element to child elements, 
such that they need not be set specifically on each element throughout an application. For details see 
Property Value Inheritance. 

11. Default value from dependency property metadata. Any given dependency property may have a 
default value as established by the property system registration of that particular property. Also, derived 
classes that inherit a dependency property have the option to override that metadata (including the 
default value) on a per-type basis. See Dependency Property Metadata for more information. Because 
inheritance is checked before default value, for an inherited property, a parent element default value takes 
precedence over a child element. Consequently, if an inheritable property is not set anywhere, the default 
value as specified on the root or parent is used instead of the child element default value. 


TemplatedParent 




TemplatedParent as a precedence item does not apply to any property of an element that you declare directly in 
standard application markup. The TemplatedParent concept exists only for child items within a visual tree that 
come into existence through the application of the template. When the property system searches the 
TemplatedParent template for a value, it is searching the template that created that element. The property values 
from the TemplatedParent template generally act as if they were set as a local value on the child element, but this 
lesser precedence versus the local value exists because the templates are potentially shared. For details, see 
TemplatedParent. 

The Style Property 

The order of lookup described earlier applies to all possible dependency properties except one: the Style 
property. The Style property is unique in that it cannot itself be styled, so the precedence items 5 through 8 do 
not apply. Also, either animating or coercing Style is not recommended (and animating Style would require a 
custom animation class). This leaves three ways that the Style property might be set: 

• Explicit style. The Style property is set directly. In most scenarios, the style is not defined inline, but 
instead is referenced as a resource, by explicit key. In this case the Style property itself acts as if it were a 
local value, precedence item 3. 

• Implicit style. The Style property is not set directly. However, the Style exists at some level in the resource 
lookup sequence (page, application) and is keyed using a resource key that matches the type the style is to 
be applied to. In this case, the Style property itself acts by a precedence identified in the sequence as item 
5. This condition can be detected by using DependencyPropertyHelper against the Style property and 
looking for ImplicitStyleReference in the results. 

• Default style, also known as theme style. The Style property is not set directly, and in fact will read as 

null up until run time. In this case, the style comes from the run-time theme evaluation that is part of the 
WPF presentation engine. 

For implicit styles not in themes, the type must match exactly - a MyButton Button -derived class will not 
implicitly use a style for Button. 

Default (Theme) Styles 

Every control that ships with WPF has a default style. That default style potentially varies by theme, which is why 
this default style is sometimes referred to as a theme style. 

The most important information that is found within a default style for a control is its control template, which 
exists in the theme style as a setter for its Template property. If there were no template from default styles, a 
control without a custom template as part of a custom style would have no visual appearance at all. The template 
from the default style gives the visual appearance of each control a basic structure, and also defines the 
connections between properties defined in the visual tree of the template and the corresponding control class. 
Each control exposes a set of properties that can influence the visual appearance of the control without 
completely replacing the template. For example, consider the default visual appearance of a Thumb control, 
which is a component of a ScrollBar. 

A Thumb has certain customizable properties. The default template of a Thumb creates a basic structure / visual 
tree with several nested Border components to create a bevel look. If a property that is part of the template is 
intended to be exposed for customization by the Thumb class, then that property must be exposed by a 
TemplateBinding, within the template. In the case of Thumb, various properties of these borders share a template 
binding to properties such as Background or BorderThickness. But certain other properties or visual 
arrangements are hard-coded into the control template or are bound to values that come directly from the 
theme, and cannot be changed short of replacing the entire template. Generally, if a property comes from a 
templated parent and is not exposed by a template binding, it cannot be adjusted by styles because there is no 
easy way to target it. But that property could still be influenced by property value inheritance in the applied 





template, or by default value. 

The theme styles use a type as the key in their definitions. However, when themes are applied to a given element 
instance, themes lookup for this type is performed by checking the DefaultStyleKey property on a control. This is 
in contrast to using the literal Type, as implicit styles do. The value of DefaultStyleKey would inherit to derived 
classes even if the implementer did not change it (the intended way of changing the property is not to override it 
at the property level, but to instead change its default value in property metadata). This indirection enables base 
classes to define the theme styles for derived elements that do not otherwise have a style (or more importantly, 
do not have a template within that style and would thus have no default visual appearance at all). Thus, you can 
derive MyButton from Button and will still get the Button default template. If you were the control author of 
MyButton and you wanted a different behavior, you could override the dependency property metadata for 
DefaultStyleKey on MyButton to return a different key, and then define the relevant theme styles including 
template for MyButton that you must package with your MyButton control. For more details on themes, styles, 
and control authoring, see Control Authoring Overview. 

Dynamic Resource References and Binding 

Dynamic resource references and binding operations respect the precedence of the location at which they are set. 
For example, a dynamic resource applied to a local value acts per precedence item 3, a binding for a property 
setter within a theme style applies at precedence item 9, and so on. Because dynamic resource references and 
binding must both be able to obtain values from the run time state of the application, this entails that the actual 
process of determining the property value precedence for any given property extends into the run time as well. 

Dynamic resource references are not strictly speaking part of the property system, but they do have a lookup 
order of their own which interacts with the sequence listed above. That precedence is documented more 
thoroughly in the XAML Resources. The basic summation of that precedence is: element to page root, application, 
theme, system. 

Dynamic resources and bindings have the precedence of where they were set, but the value is deferred. One 
consequence of this is that if you set a dynamic resource or binding to a local value, any change to the local value 
replaces the dynamic resource or binding entirely. Even if you call the ClearValue method to clear the locally set 
value, the dynamic resource or binding will not be restored. In fact, if you call ClearValue on a property that has a 
dynamic resource or binding in place (with no literal local value), they are cleared by the ClearValue call too. 

SetCurrentValue 

The SetCurrentValue method is another way to set a property, but it is not in the order of precedence. Instead, 
SetCurrentValue enables you to change the value of a property without overwriting the source of a previous 
value. You can use SetCurrentValue any time that you want to set a value without giving that value the 
precedence of a local value. For example, if a property is set by a trigger and then assigned another value via 
SetCurrentValue, the property system still respects the trigger and the property will change if the trigger's action 
occurs. SetCurrentValue enables you to change the property's value without giving it a source with a higher 
precedence. Likewise, you can use SetCurrentValue to change the value of a property without overwriting a 
binding. 

Coercion, Animations, and Base Value 

Coercion and animation both act on a value that is termed as the "base value" throughout this SDK. The base 
value is thus whatever value is determined through evaluating upwards in the items until item 2 is reached. 

For an animation, the base value can have an effect on the animated value, if that animation does not specify 
both "From" and "To" for certain behaviors, or if the animation deliberately reverts to the base value when 
completed. To see this in practice, run the From, To, and By Animation Target Values Sample. Try setting the local 
values of the rectangle height in the example, such that the initial local value differs from any "From" in the 





animation. You will note that the animations start right away using the "From" values and replace the base value 
once started. The animation might specify to return to the value found before animation once it is completed by 
specifying the Stop FillBehavior. Afterwards, normal precedence is used for the base value determination. 

Multiple animations might be applied to a single property, with each of these animations possibly having been 
defined from different points in the value precedence. However, these animations will potentially composite their 
values, rather than just applying the animation from the higher precedence. This depends on exactly how the 
animations are defined, and the type of the value that is being animated. For more information about animating 
properties, see Animation Overview. 

Coercion applies at the highest level of all. Even an already running animation is subject to value coercion. 
Certain existing dependency properties in WPF have built-in coercion. For a custom dependency property, you 
define the coercion behavior for a custom dependency property by writing a CoerceValueCallback and passing 
the callback as part of metadata when you create the property. You can also override coercion behavior of 
existing properties by overriding the metadata on that property in a derived class. Coercion interacts with the 
base value in such a way that the constraints on coercion are applied as those constraints exist at the time, but 
the base value is still retained. Therefore, if constraints in coercion are later lifted, the coercion will return the 
closest value possible to that base value, and potentially the coercion influence on a property will cease as soon 
as all constraints are lifted. For more information about coercion behavior, see Dependency Property Callbacks 
and Validation. 

Trigger Behaviors 

Controls often define trigger behaviors as part of their default style in themes. Setting local properties on 
controls might prevent the triggers from being able to respond to user-driven events either visually or 
behaviorally. The most common use of a property trigger is for control or state properties such as IsSelected. For 
example, by default when a Button is disabled (trigger for IsEnabled is false ) then the Foreground value in the 
theme style is what causes the control to appear "grayed out". But if you have set a local Foreground value, that 
normal gray-out color will be overruled in precedence by your local property set, even in this property-triggered 
scenario. Be cautious of setting values for properties that have theme-level trigger behaviors and make sure you 
are not unduly interfering with the intended user experience for that control. 

ClearValue and Value Precedence 

The ClearValue method provides an expedient means to clear any locally applied value from a dependency 
property that is set on an element. However, calling ClearValue is not a guarantee that the default as established 
in metadata during property registration is the new effective value. All of the other participants in value 
precedence are still active. Only the locally set value has been removed from the precedence sequence. For 
example, if you call ClearValue on a property where that property is also set by a theme style, then the theme 
value is applied as the new value rather than the metadata-based default. If you want to take all property value 
participants out of the process and set the value to the registered metadata default, you can obtain that default 
value definitively by querying the dependency property metadata, and then you can use the default value to 
locally set the property with a call to SetValue. 

See also 

• DependencyObJect 

• DependencyProperty 

• Dependency Properties Overview 

• Custom Dependency Properties 

• Dependency Property Callbacks and Validation 
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This topic describes read-only dependency properties, including existing read-only dependency properties and the 
scenarios and techniques for creating a custom read-only dependency property. 

Prerequisites 

This topic assumes that you understand the basic scenarios of implementing a dependency property, and how 
metadata is applied to a custom dependency property. See Custom Dependency Properties and Dependency 
Property Metadata for context. 

Existing Read-Only Dependency Properties 

Some of the dependency properties defined in the Windows Presentation Foundation (WPF) framework are read¬ 
only. The typical reason for specifying a read-only dependency property is that these are properties that should be 
used for state determination, but where that state is influenced by a multitude of factors, but just setting the 
property to that state isn't desirable from a user interface design perspective. For example, the property 
IsMouseOver is reallyjust surfacing state as determined from the mouse input. Any attempt to set this value 
programmatically by circumventing the true mouse input would be unpredictable and would cause inconsistency. 

By virtue of not being settable, read-only dependency properties aren't appropriate for many of the scenarios for 
which dependency properties normally offer a solution (namely: data binding, directly stylable to a value, 
validation, animation, inheritance). Despite not being settable, read-only dependency properties still have some of 
the additional capabilities supported by dependency properties in the property system. The most important 
remaining capability is that the read-only dependency property can still be used as a property trigger in a style. 
You can't enable triggers with a normal common language runtime (CLR) property; it needs to be a dependency 
property. The aforementioned IsMouseOver property is a perfect example of a scenario where it might be quite 
useful to define a style for a control, where some visible property such as a background, foreground, or similar 
properties of composited elements within the control will change when the user places a mouse over some 
defined region of your control. Changes in a read-only dependency property can also be detected and reported by 
the property system's inherent invalidation processes, and this in fact supports the property trigger functionality 
internally. 

Creating Custom Read-Only Dependency Properties 

Make sure to read the section above regarding why read-only dependency properties won't work for many typical 
dependency-property scenarios. But if you have an appropriate scenario, you may wish to create your own read¬ 
only dependency property. 

Much of the process of creating a read-only dependency property is the same as is described in the Custom 
Dependency Properties and Implement a Dependency Property topics. There are three important differences: 

• When registering your property, call the RegisterReadOnly method instead of the normal Register method 
for property registration. 

• When implementing the CLR "wrapper" property, make sure that the wrapper too doesn't have a set 
implementation, so that there is no inconsistency in read-only state for the public wrapper you expose. 

• The object returned by the read-only registration is DependencyPropertyKey rather than 
DependencyProperty. You should still store this field as a member but typically you would not make it a 




public member of the type. 

Whatever private field or value you have backing your read-only dependency property can of course be fully 
writable using whatever logic you decide. However, the most straightforward way to set the property either 
initially or as part of runtime logic is to use the property system's APIs, rather than circumventing the property 
system and setting the private backing field directly. In particular, there is a signature of SetValue that accepts a 
parameter of type DependencyPropertyKey. How and where you set this value programmatically within your 
application logic will affect how you may wish to set access on the DependencyPropertyKey created when you first 
registered the dependency property. If you handle this logic all within the class you could make it private, or if you 
require it to be set from other portions of the assembly you might set it internal. One approach is to call SetValue 
within a class event handler of a relevant event that informs a class instance that the stored property value needs 
to be changed. Another approach is to tie dependency properties together by using paired 
PropertyChangedCallback and CoerceValueCallback callbacks as part of those properties' metadata during 
registration. 

Because the DependencyPropertyKey is private, and is not propagated by the property system outside of your 
code, a read-only dependency property does have better setting security than a read-write dependency property. 
For a read-write dependency property, the identifying field is explicitly or implicitly public and thus the property is 
widely settable. For more specifics, see Dependency Property Security. 

See also 

• Dependency Properties Overview 

• Custom Dependency Properties 

• Styling and Templating 
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Property value inheritance is a feature of the Windows Presentation Foundation (WPF) property system. Property 
value inheritance enables child elements in a tree of elements to obtain the value of a particular property from 
parent elements, inheriting that value as it was set anywhere in the nearest parent element. The parent element 
might also have obtained its value through property value inheritance, so the system potentially recurses all the 
way to the page root. Property value inheritance is not the default property system behavior; a property must be 
established with a particular metadata setting in order to cause that property to initiate property value 
inheritance on child elements. 

Property Value Inheritance Is Containment Inheritance 

"Inheritance" as a term here is not quite the same concept as inheritance in the context of types and general 
object-oriented programming, where derived classes inherit member definitions from their base classes. That 
meaning of inheritance is also active in WPF; properties defined in various base classes are exposed as attributes 
for derived XAML classes when used as elements, and exposed as members for code. Property value inheritance 
is particularly about how property values can inherit from one element to another on the basis of the parent- 
child relationships within a tree of elements. That tree of elements is most directly visible when nesting elements 
inside other elements as you define applications in XAML markup. Trees of objects can also be created 
programmatically by adding objects to designated collections of other objects, and property value inheritance 
works the same way in the finished tree at run time. 

Practical Applications of Property Value Inheritance 

The WPF APIs include several properties that have property inheritance enabled. Typically, the scenario for these 
is that they involve a property where it is appropriate that the property be set only once per page, but where that 
property is also a member of one of the base element classes and thus would also exist on most of the child 
elements. For example, the FlowDirection property controls which direction flowed content should be presented 
and arranged on the page. Typically, you want the text flow concept to be handled consistently throughout all 
child elements. If flow direction were for some reason reset in some level of the element tree by user or 
environment action, it should typically be reset throughout. When the FlowDirection property is made to inherit, 
the value need only be set or reset once at the level in the element tree that encompasses the presentation needs 
of each page in the application. Even the initial default value will inherit in this way. The property value 
inheritance model still enables individual elements to reset the value for the rare cases where having a mix of 
flow directions is intentional. 

Making a Custom Property Inheritable 

By changing a custom property's metadata, you can also make your own custom properties inheritable. Note, 
however, that designating a property as inheritable does have some performance considerations. In cases where 
that property does not have an established local value, or a value obtained through styles, templates, or data 
binding, an inheritable property provides its assigned property values to all child elements in the logical tree. 

To make a property participate in value inheritance, create a custom attached property, as described in Register 
an Attached Property. Register the property with metadata (FrameworkPropertyMetadata) and specify the 
"Inherits" option in the options settings within that metadata. Also make sure that the property has an 
established default value, because that value will now inherit. Although you registered the property as attached, 
you might also want to create a property "wrapper" for get/set access on the owner type. Just as you would for 




an "nonattached" dependency property. After doing so, the inheritable property can either be set by using the 
direct property wrapper on the owner type or derived types, or it can be set by using the attached property 
syntax on any DependencyObject. 

Attached properties are conceptually similar to global properties; you can check for the value on any 
DependencyObject and get a valid result. The typical scenario for attached properties is to set property values on 
child elements, and that scenario is more effective if the property in question is an attached property that is 
always implicitly present as an attached property on each element (DependencyObject) in the tree. 


NOTE 

Although property value inheritance might appear to work for nonattached dependency properties, the inheritance 
behavior for a nonattached property through certain element boundaries in the run-time tree is undefined. Always use 
RegisterAttached to register properties where you specify Inherits in the metadata. 


Inheriting Property Values Across Tree Boundaries 

Property inheritance works by traversing a tree of elements. This tree is often parallel to the logical tree. However, 
whenever you include a WPF core-level object in the markup that defines an element tree, such as a Brush, you 
have created a discontinuous logical tree. A true logical tree does not conceptually extend through the Brush, 
because the logical tree is a WPF framework-level concept. You can see this reflected in the results when using 
the methods of LogicalTreeHelper. However, property value inheritance can bridge this gap in the logical tree and 
can still pass inherited values through, so long as the inheritable property was registered as an attached property 
and no deliberate inheritance-blocking boundary (such as a Frame) is encountered. 

See also 

• Dependency Property Metadata 

• Attached Properties Overview 

• Dependency Property Value Precedence 
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Dependency properties should generally be considered to be public properties. The nature of the Windows 
Presentation Foundation (WPF) property system prevents the ability to make security guarantees about a 
dependency property value. 

Access and Security of Wrappers and Dependency Properties 

Typically, dependency properties are implemented along with "wrapper" common language runtime (CLR) 
properties that simplify getting or setting the property from an instance. But the wrappers are really just 
convenience methods that implement the underlying GetValue and SetValue static calls that are used when 
interacting with dependency properties. Thinking of it in another way, the properties are exposed as common 
language runtime (CLR) properties that happen to be backed by a dependency property rather than by a private 
field. Security mechanisms applied to the wrappers do not parallel the property system behavior and access of 
the underlying dependency property. Placing a security demand on the wrapper will only prevent the usage of the 
convenience method but will not prevent calls to GetValue or SetValue. Similarly, placing protected or private 
access level on the wrappers does not provide any effective security. 

If you are writing your own dependency properties, you should declare the wrappers and the 
DependencyProperty identifier field as public members, so that callers do not get misleading information about 
the true access level of that property (because of its store being implemented as a dependency property). 

For a custom dependency property, you can register your property as a read-only dependency property, and this 
does provide an effective means of preventing a property being set by anyone that does not hold a reference to 
the DependencyPropertyKey for that property. For more information, see Read-Only Dependency Properties. 


NOTE 

Declaring a DependencyProperty identifier field private is not forbidden, and it can conceivably be used to help reduce the 
immediately exposed namespace of a custom class, but such a property should not be considered "private" in the same 
sense as the common language runtime (CLR) language definitions define that access level, for reasons described in the 
next section. 


Property System Exposure of Dependency Properties 

It is not generally useful, and it is potentially misleading, to declare a DependencyProperty as any access level 
other than public. That access level setting only prevents someone from being able to get a reference to the 
instance from the declaring class. But there are several aspects of the property system that will return a 
DependencyProperty as the means of identifying a particular property as it exists on an instance of a class or a 
derived class instance, and this identifier is still usable in a SetValue call even if the original static identifier is 
declared as nonpublic. Also, OnPropertyChanged virtual methods receive information of any existing dependency 
property that changed value. In addition, the GetLocalValueEnumerator method returns identifiers for any 
property on instances with a locally set value. 

Validation and Security 

Applying a demand to a ValidateValueCallback and expecting the validation failure on a demand failure to prevent 
a property from being set is not an adequate security mechanism. Set-value invalidation enforced through 
ValidateValueCallback could also be suppressed by malicious callers, if those callers are operating within the 
application domain. 





See also 

• Custom Dependency Properties 
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Generally, class constructors should not call callbacks such as virtual methods or delegates, because constructors 
can be called as base initialization of constructors for a derived class. Entering the virtual might be done at an 
incomplete initialization state of any given object. However, the property system itself calls and exposes callbacks 
internally, as part of the dependency property system. As simple an operation as setting a dependency property 
value with SetValue call potentially includes a callback somewhere in the determination. For this reason, you 
should be careful when setting dependency property values within the body of a constructor, which can become 
problematic if your type is used as a base class. There is a particular pattern for implementing DependencyObJect 
constructors that avoids specific problems with dependency property states and the inherent callbacks, which is 
documented here. 

Property System Virtual Methods 

The following virtual methods or callbacks are potentially called during the computations of the SetValue call that 
sets a dependency property value: ValidateValueCallback, PropertyChangedCallback, CoerceValueCallback, 
OnPropertyChanged. Each of these virtual methods or callbacks serves a particular purpose in expanding the 
versatility of the Windows Presentation Foundation (WPF) property system and dependency properties. For more 
information on how to use these virtuals to customize property value determination, see Dependency Property 
Callbacks and Validation. 

FXCop Rule Enforcement vs. Property System Virtuals 

If you use the Microsoft tool FXCop as part of your build process, and you either derive from certain WPF 
framework classes calling the base constructor, or implement your own dependency properties on derived classes, 
you might encounter a particular FXCop rule violation. The name string for this violation is: 

DoNotCallOvenridableMethodsInConstructors 

This is a rule that is part of the default public rule set for FXCop. What this rule might be reporting is a trace 
through the dependency property system that eventually calls a dependency property system virtual method. This 
rule violation might continue to appear even after following the recommended constructor patterns documented 
in this topic, so you might need to disable or suppress that rule in your FXCop rule set configuration. 

Most Issues Come From Deriving Classes, Not Using Existing Classes 

The issues reported by this rule occur when a class that you implement with virtual methods in its construction 
sequence is then derived from. If you seal your class, or otherwise know or enforce that your class will not be 
derived from, the considerations explained here and the issues that motivated the FXCop rule do not apply to you. 
However, if you are authoring classes in such a way that they are intended to be used as base classes, for instance 
if you are creating templates, or an expandable control library set, you should follow the patterns recommended 
here for constructors. 

Default Constructors Must Initialize All Values Requested By Callbacks 

Any instance members that are used by your class overrides or callbacks (the callbacks from the list in the 
Property System Virtuals section) must be initialized in your class parameterless constructor, even if some of those 
values are filled by "real" values through parameters of the nonparameterless constructors. 

The following example code (and subsequent examples) is a pseudo-C# example that violates this rule and 
explains the problem: 





public class MyClass : DependencyObject 

{ 

public MyClassO {} 

public MyClass(object toSetWobble) 

: thisO 

{ 

Wobble = toSetWobble; //this is backed by a DependencyProperty 
_myList = new ArnayList(); // this line should be in the default ctor 

} 

public static readonly DependencyProperty WobbleProperty = 

DependencyProperty.Register("Wobble ", typeof(object), typeof(MyClass)); 
public object Wobble 
{ 

get { return GetValue(WobbleProperty); } 
set { Set\/alue(WobbleProperty^ value); } 

} 

protected override void OnPropertyChanged(DependencyPropertyChangedEventArgs e) 

{ 

int count = _myList.Count; // null-reference exception 

} 

private ArrayList _myList; 

} 

When application code calls new Myciass(objectvaiue) , this calls the parameterless constructor and base class 
constructors. Then it sets Propertyi = objecti , which calls the virtual method onPropertyChanged on the owning 
MyClass DependencyObject. The override refers to _myList , which has not been initialized yet. 

One way to avoid these issues is to make sure that callbacks use only other dependency properties, and that each 
such dependency property has an established default value as part of its registered metadata. 

Safe Constructor Patterns 

To avoid the risks of incomplete initialization if your class is used as a base class, follow these patterns: 

Parameterless constructors calling base initialization 

Implement these constructors calling the base default: 

public MyClass : SomeBaseClass { 
public MyClassO : base() { 

// ALL class initialization, including initial defaults for 
// possible values that other ctors specify or that callbacks need. 

} 

} 

Non-default (convenience) constructors, not matching any base signatures 

If these constructors use the parameters to set dependency properties in the initialization, first call your own class 
parameterless constructor for initialization, and then use the parameters to set dependency properties. These 
could either be dependency properties defined by your class, or dependency properties inherited from base 
classes, but in either case use the following pattern: 

public MyClass : SomeBaseClass { 

public MyClass(object toSetPropentyl) : this() { 

// Class initialization MOT done by default. 

// Then, set properties to values as passed in ctor parameters. 

Propertyi = toSetPropertyl; 

} 

} 


Non-default (convenience) constructors, which do match base signatures 










Instead of calling the base constructor with the same parameterization, again call your own class' parameterless 
constructor. Do not call the base initializer; instead you should call this() . Then reproduce the original 
constructor behavior by using the passed parameters as values for setting the relevant properties. Use the original 
base constructor documentation for guidance in determining the properties that the particular parameters are 
intended to set: 

public MyClass : SomeBaseClass { 

public MyClass(object toSetPnopentyl) : this() { 

// Class initialization NOT done by default. 

// Then, set properties to values as passed in ctor parameters. 

Propertyl = toSetPropertyl; 

} 

} 

Must match all signatures 

For cases where the base type has multiple signatures, you must deliberately match all possible signatures with a 
constructor implementation of your own that uses the recommended pattern of calling the class parameterless 
constructor before setting further properties. 

Setting dependency properties with SetValue 

These same patterns apply if you are setting a property that does not have a wrapper for property setting 
convenience, and set values with SetValue. Your calls to SetValue that pass through constructor parameters should 
also call the class' parameterless constructor for initialization. 

See also 

• Custom Dependency Properties 

• Dependency Properties Overview 

• Dependency Property Security 
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This topic provides guidance and suggested patterns for how to implement a dependency property where the type 
of the property is a collection type. 

Implementing a Collection-Type Dependency Property 

For a dependency property in general, the implementation pattern that you follow is that you define a CLR 
property wrapper, where that property is backed by a DependencyProperty identifier rather than a field or other 
construct. You follow this same pattern when you implement a collection-type property. However, a collection-type 
property introduces some complexity to the pattern whenever the type that is contained within the collection is 
itself a DependencyObject or Freezable derived class. 

Initializing the Collection Beyond the Default Value 

When you create a dependency property, you do not specify the property default value as the initial field value. 
Instead, you specify the default value through the dependency property metadata. If your property is a reference 
type, the default value specified in dependency property metadata is not a default value per instance; instead it is a 
default value that applies to all instances of the type. Therefore you must be careful to not use the singular static 
collection defined by the collection property metadata as the working default value for newly created instances of 
your type. Instead, you must make sure that you deliberately set the collection value to a unique (instance) 
collection as part of your class constructor logic. Otherwise you will have created an unintentional singleton class. 

Consider the following example. The following section of the example shows the definition for a class Aquarium , 
which contains a flaw with the default value. The class defines the collection type dependency property 
AquariumObjects , which uses the generic List<T> type with a FrameworkElement type constraint. In the 
Register(String, Type, Type, PropertyMetadata) call for the dependency property, the metadata establishes the 
default value to be a new generic List<T>. 


WARNING 

The following code does not behave correctly. 







public class Fish : FrameworkElement { } 
public class Aquarium : DependencyObject { 

private static readonly DependencyPropertyKey AquariumContentsPropertyKey = 
DependencyProperty.RegisterReadOnly( 

"AquariumContents"j 

typeof (List<Frameworl<Element>) j 

typeof(Aquarium)j 

new FrameworkPropertyMetadata(new List<FrameworkElement>()) 

); 

public static readonly DependencyProperty AquariumContentsProperty = 
AquariumContentsPropertyKey.DependencyProperty; 

public List<FrameworkElement> AquariumContents 

{ 

get { return (List<FrameworkElement>)GetValue(AquariumContentsProperty); } 

} 

H ... 

} 


Public Class Fish 

Inherits FrameworkElement 
End Class 

Public Class Aquarium 

Inherits DependencyObject 

Private Shared Readonly AquariumContentsPropertyKey As DependencyPropertyKey = 

DependencyProperty.RegisterReadOnly("AquariumContents ", GetType(List(Of ErameworkElement )), Getlype(Aquarium)j 
New PrameworkPropertyMetadata(New List(Of PrameworkElement)())) 

Public Shared Readonly AquariumContentsProperty As DependencyProperty = 

AquariumContentsPropertyKey.DependencyProperty 

Public Readonly Property AquariumContents() As List(Of FrameworkElement) 

Get 

Return CType(GetValue(AquariumContentsProperty)j List(Of FrameworkElement)) 

End Get 
End Property 


End Class 

However, if you just left the code as shown, that single list default value is shared for all instances of Aquarium . If 
you ran the following test code, which is intended to show how you would instantiate two separate Aquarium 
instances and add a single different Eish to each of them, you would see a surprising result: 

Aquarium myAql = new Aquarium(); 

Aquarium myAq2 = new Aquarium(); 

Eish fl = new Fish(); 

Eish f2 = new Fish(); 

myAql.AquariumContents.Add(fl); 

myAq2.AquariumContents.Add(f2); 

MessageBox.Show("aql contains " + myAql.AquariumContents.Count.ToStringO + " things"); 

MessageBox.Show("aq2 contains " + myAq2.AquariumContents.Count.ToStringO + " things"); 







Dim myAql As New Aquarium() 

Dim myAq2 As New Aquarium() 

Dim fl As New Fish() 

Dim f2 As New Fish() 

myAql.AquariumContents.Add(fl) 

myAq2.AquariumContents.Add(f2) 

MessageBox.Show("aql contains " & myAql.AquaniumContents.Count.ToStringO & " things") 

MessageBox.Show("aq2 contains " & myAq2.AquaniumContents.Count.ToStringO & " things") 

Instead of each collection having a count of one, each collection has a count of two! This is because each Aquarium 
added its Fish to the default value collection, which resulted from a single constructor call in the metadata and is 
therefore shared between all instances. This situation is almost never what you want. 

To correct this problem, you must reset the collection dependency property value to a unique instance, as part of 
the class constructor call. Because the property is a read-only dependency property, you use the 
SetValue(DependencyPropertyKey, Object) method to set it, using the DependencyPropertyKey that is only 
accessible within the class. 


public AquariumO : base() 

{ 

SetValue(AquariumContentsPropertyKeyj new List<FrameworkElement>())j 

} 


Public Sub New() 

MyBase.NewO 

SetValue(AquariumContentsPropertyKeyj New List(Of FrameworkElement)()) 

End Sub 

Now, if you ran that same test code again, you could see more expected results, where each Aquarium supported 
its own unique collection. 

There would be a slight variation on this pattern if you chose to have your collection property be read-write. In 
that case, you could call the public set accessor from the constructor to do the initialization, which would still be 
calling the nonkey signature of SetValue(DependencyProperty, Object) within your set wrapper, using a public 
DependencyProperty identifier. 

Reporting Binding Value Changes from Collection Properties 

A collection property that is itself a dependency property does not automatically report changes to its 
subproperties. If you are creating bindings into a collection, this can prevent the binding from reporting changes, 
thus invalidating some data binding scenarios. However, if you use the collection type FreezableCollection<T> as 
your collection type, then subproperty changes to contained elements in the collection are properly reported, and 
binding works as expected. 

To enable subproperty binding in a dependency object collection, create the collection property as type 
FreezableCollection<T>, with a type constraint for that collection to any DependencyObJect derived class. 

See also 

• FreezableCollection<T> 

• XAML and Custom Classes for WPF 

• Data Binding Overview 

• Dependency Properties Overview 

• Custom Dependency Properties 
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The current WPF implementation of its XAML processor is inherently dependency property aware. The WPF XAML 
processor uses property system methods for dependency properties when loading binary XAML and processing 
attributes that are dependency properties. This effectively bypasses the property wrappers. When you implement 
custom dependency properties, you must account for this behavior and should avoid placing any other code in 
your property wrapper other than the property system methods GetValue and SetValue. 

Prerequisites 

This topic assumes that you understand dependency properties both as consumer and author and have read 
Dependency Properties Overview and Custom Dependency Properties. You should also have read XAML 
Overview (WPF) and XAML Syntax In Detail. 

The WPF XAML Loader Implementation, and Performance 

For implementation reasons, it is computationally less expensive to identify a property as a dependency property 
and access the property system SetValue method to set it, rather than using the property wrapper and its setter. 
This is because a XAML processor must infer the entire object model of the backing code based only on knowing 
the type and member relationships that are indicated by the structure of the markup and various strings. 

The type is looked up through a combination of xmlns and assembly attributes, but identifying the members, 
determining which could support being set as an attribute, and resolving what types the property values support 
would otherwise require extensive reflection using Propertyinfo. Because dependency properties on a given type 
are accessible as a storage table through the property system, the WPF implementation of its XAML processor 
uses this table and infers that any given property ABC can be more efficiently set by calling SetValue on the 
containing DependencyObJect derived type, using the dependency property identifier ABCProperty. 

Implications for Custom Dependency Properties 

Because the current WPF implementation of the XAML processor behavior for property setting bypasses the 
wrappers entirely, you should not put any additional logic into the set definitions of the wrapper for your custom 
dependency property. If you put such logic in the set definition, then the logic will not be executed when the 
property is set in XAML rather than in code. 

Similarly, other aspects of the XAML processor that obtain property values from XAML processing also use 
GetValue rather than using the wrapper. Therefore, you should also avoid any additional implementation in the 
get definition beyond the GetValue call. 

The following example is a recommended dependency property definition with wrappers, where the property 
identifier is stored as a public static readonly field, and the get and set definitions contain no code 
beyond the necessary property system methods that define the dependency property backing. 








public static readonly DependencyProperty AquariumGraphicProperty = DependencyProperty.Register( 
"AquariumGraphic"j 
typeof(Uri) j 
typeof(AquariumObject)j 
new FrameworkPropertyMetadata(nullj 

FrameworkPropertyMetadataOptions.AffectsRenderj 
new PropertyChangedCallback(OnLlriChanged) 

) 

); 

public Uri AquariumGraphic 

{ 

get { return (Uri)GetValue(AquariumGraphicProperty); } 
set { SetValue(AquariumGraphicPropertyj value); } 


Public Shared Readonly AquariumGraphicProperty As DependencyProperty = 

DependencyProperty.Register("AquariumGraphic"j GetType(Llri), GetType(AquariumObject)j New 
FrameworkPropertyMetadata(Nothing, FrameworkPropertyMetadataOptions.AffectsRender, New 
PropertyChangedCallback(AddressOf OnUriChanged))) 

Public Property AquariumGraphic() As Uri 
Get 

Return CType(Get\/alue(AquariumGraphicProperty), Uri) 

End Get 

Set(By\/al value As Uri) 

SetValue(AquariumGraphicProperty, value) 

End Set 
End Property 


See also 

• Dependency Properties Overview 

• XAML Overview (WPF) 

• Dependency Property Metadata 

• Collection-Type Dependency Properties 

• Dependency Property Security 

• Safe Constructor Patterns for DependencyObjects 
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This example shows how to back a common language runtime (CLR) property with a DependencyProperty field, 
thus defining a dependency property. When you define your own properties and want them to support many 
aspects of Windows Presentation Foundation (WPF) functionality, including styles, data binding, inheritance, 
animation, and default values, you should implement them as a dependency property. 

Example 

The following example first registers a dependency property by calling the Register method. The name of the 
identifier field that you use to store the name and characteristics of the dependency property must be the Name 
you chose for the dependency property as part of the Register call, appended by the literal string Property . For 
instance, if you register a dependency property with a Name of Location , then the identifier field that you define 
for the dependency property must be named LocationProperty . 

In this example, the name of the dependency property and its CLR accessor is state ; the identifier field is 
stateProperty ; the type of the property is Boolean; and the type that registers the dependency property is 
MyStateControl . 


If you fail to follow this naming pattern, designers might not report your property correctly, and certain aspects of 
property system style application might not behave as expected. 

You can also specify default metadata for a dependency property. This example registers the default value of the 
state dependency property to be false . 

public class MyStateControl : ButtonBase 

{ 

public MyStateControlO : base() { } 
public Boolean State 
{ 

get { return (Boolean)this.GetValue(StateProperty); } 
set { this.SetValue(StateProperty, value); } 

} 

public static readonly DependencyProperty StateProperty = DependencyProperty.Register( 

"State", typeof(Boolean), typeof(MyStateControl),new PropertyMetadata(false))j 

} 


Public Class MyStateControl 
Inherits ButtonBase 
Public Sub New() 

MyBase.NewO 
End Sub 

Public Property State() As Boolean 
Get 

Return CType(Me.GetValue(StateProperty), Boolean) 

End Get 

Set(ByVal value As Boolean) 

Me.SetValue(StateProperty, value) 

End Set 
End Property 

Public Shared Readonly StateProperty As DependencyProperty = DependencyProperty.Register("State", 
GetType(Boolean), GetType(MyStateControl),New PropertyMetadata(False)) 

End Class 






For more information about how and why to implement a dependency property, as opposed to just backing a CLR 
property with a private field, see Dependency Properties Overview. 


See also 

• Dependency Properties Overview 

• How-to Topics 


How to: Add an Owner Type for a Dependency 
Property 
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This example shows how to add a class as an owner of a dependency property registered for a different type. By 
doing this, the WPF XAML reader and property system are both able to recognize the class as an additional owner 
of the property. Adding as owner optionally allows the adding class to provide type-specific metadata. 

In the following example, statePnopenty is a property registered by the MystateControi class. The class 
unreiatedstateControi adds itself as an owner of the stateProperty using the AddOwner method, specifically 
using the signature that allows for new metadata for the dependency property as it exists on the adding type. 
Notice that you should provide common language runtime (CLR) accessors for the property similar to the example 
shown in the Implement a Dependency Property example, as well as re-expose the dependency property identifier 
on the class being added as owner. 

Without wrappers, the dependency property would still work from the perspective of programmatic access using 
GetValue or SetValue. But you typically want to parallel this property-system behavior with the CLR property 
wrappers. The wrappers make it easier to set the dependency property programmatically, and make it possible to 
set the properties as XAML attributes. 

To find out how to override default metadata, see Override Metadata for a Dependency Property. 

Example 

public class MyStateControl : ButtonBase 

{ 

public MyStateControl() : base() { } 
public Boolean State 
{ 

get { return (Boolean)this.GetValue(StateProperty)j } 
set { this.SetValue(StatePropertyj value); } 

} 

public static readonly DependencyProperty StateProperty = DependencyProperty.Register( 

"State"j typeof(Boolean), typeof(MyStateControl)jnew PropertyMetadata(false)); 

} 


Public Class MyStateControl 
Inherits ButtonBase 
Public Sub Mew() 

MyBase.MewO 
End Sub 

Public Property State() As Boolean 
Get 

Return CType(Me.GetValue(StateProperty), Boolean) 

End Get 

Set(ByVal value As Boolean) 

Me.SetValue(StatePropertyj value) 

End Set 
End Property 

Public Shared Readonly StateProperty As DependencyProperty = DependencyProperty.Register("State"j 
GetType(Boolean), GetType(MyStateControl),New PropertyMetadata(False)) 

End Class 









public class UnrelatedStateControl : Control 

{ 

public UnrelatedStateControlO { } 

public static readonly DependencyProperty StateProperty = 
MyStateControl.StateProperty.AddOwner(typeof(UnrelatedStateControl), new PropertyMetadata(true)); 
public Boolean State 
{ 

get { return (Boolean)this.Get\/alue(StateProperty)j } 
set { this.Set\/alue(StateProperty, value); } 

} 


Public Class UnrelatedStateControl 
Inherits Control 
Public Sub IMew() 

End Sub 

Public Shared Readonly StateProperty As DependencyProperty = 
MyStateControl.StateProperty.AddOwner(GetType(UnrelatedStateControl), New PropertyMetadata(True)) 
Public Property State() As Boolean 
Get 

Return CType(Me.GetValue(StateProperty), Boolean) 

End Get 

Set(By\/al value As Boolean) 

Me.Set\/alue(StateProperty, value) 

End Set 
End Property 
End Class 


See also 


• Custom Dependency Properties 

• Dependency Properties Overview 



How to: Register an Attached Property 
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This example shows how to register an attached property and provide public accessors so that you can use the 
property in both Extensible Application Markup Language (XAML) and code. Attached properties are a syntax 
concept defined by Extensible Application Markup Language (XAML). Most attached properties for WPF types are 
also implemented as dependency properties. You can use dependency properties on any DependencyObject types. 

Example 

The following example shows how to register an attached property as a dependency property, by using the 
RegisterAttached method. The provider class has the option of providing default metadata for the property that is 
applicable when the property is used on another class, unless that class overrides the metadata. In this example, 
the default value of the isBubbieSource property is set to false. 

The provider class for an attached property (even if it is not registered as a dependency property) must provide 
static get and set accessors that follow the naming convention set [AttachedPropertyName]and Get 
[AttachedPropertyName], These accessors are required so that the acting XAML reader can recognize the property 
as an attribute in XAML and resolve the appropriate types. 

public static readonly DependencyProperty IsBubbleSourceProperty = DependencyProperty.RegisterAttached( 
"IsBubbieSource"j 
typeof(Boolean)j 
typeof(AquariumObject), 

new FrameworkPropertyMetadata(falsej FrameworkPropertyMetadataOptions.AffectsRender) 

); 

public static void SetIsBubbleSource(UIElement elementj Boolean value) 

{ 

element.SetValue(IsBubbleSourcePropertyj value); 

} 

public static Boolean GetIsBubbleSource(LIIElement element) 

{ 

return (Boolean)element.GetValue(IsBubbleSourceProperty); 

} 


Public Shared Readonly IsBubbleSourceProperty As DependencyProperty = 

DependencyProperty.RegisterAttached("IsBubbieSource"j GetType(Boolean)j GetType(AquariumObject), New 
FrameworkPropertyMetadata(False, FrameworkPropertyMetadataOptions.AffectsRender)) 

Public Shared Sub SetIsBubbleSource(ByVal element As UIElementj ByVal value As Boolean) 
element.SetValue(IsBubbleSourceProperty, value) 

End Sub 

Public Shared Function GetIsBubbleSource(ByVal element As UIElement) As Boolean 
Return CType(element.GetValue(IsBubbleSourceProperty), Boolean) 

End Function 


See also 

• DependencyProperty 

• Dependency Properties Overview 

• Custom Dependency Properties 

• How-to Topics 








How to: Override Metadata for a Dependency 
Property 
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This example shows how to override default dependency property metadata that comes from an inherited class, 
by calling the OverrideMetadata method and providing type-specific metadata. 

Example 

By defining its PropertyMetadata, a class can define the dependency property's behaviors, such as its default value 
and property system callbacks. Many dependency property classes already have default metadata established as 
part of their registration process. This includes the dependency properties that are part of the WPF API. A class 
that inherits the dependency property through its class inheritance can override the original metadata so that the 
characteristics of the property that can be altered through metadata will match any subclass-specific requirements. 

Overriding metadata on a dependency property must be done prior to that property being placed in use by the 
property system (this equates to the time that specific instances of objects that register the property are 
instantiated). Calls to OverrideMetadata must be performed within the static constructors of the type that provides 
itself as the foriype parameter of OverrideMetadata. If you attempt to change metadata once instances of the 
owner type exist, this will not raise exceptions, but will result in inconsistent behaviors in the property system. 

Also, metadata can only be overridden once per type. Subsequent attempts to override metadata on the same type 
will raise an exception. 

In the following example, the custom class MyAdvancedstateControi overrides the metadata provided for 
stateProperty by MyAdvancedstateControi with new property metadata. For instance, the default value of the 
StateProperty is now true when the property is queried on a newly constructed MyAdvancedstateControi 
instance. 

public class MyStateControl : ButtonBase 
{ 

public MyStateControl() : base() { } 
public Boolean State 
{ 

get { return (Boolean)this.GetValue(StateProperty)j } 
set { this.SetValue(StatePropertyj value); } 

} 

public static readonly DependencyProperty StateProperty = DependencyProperty.Register( 

"State", typeof(Boolean), typeof(MyStateControl),new PropertyMetadata(false)); 

} 









Public Class MyStateControl 
Inherits ButtonBase 
Public Sub New() 

MyBase.NewO 
End Sub 

Public Property State() As Boolean 
Get 

Return CType(Me.GetValue(StateProperty)j Boolean) 

End Get 

Set(By\/al value As Boolean) 

Me.Set\/alue(StatePropertyj value) 

End Set 
End Property 

Public Shared Readonly StateProperty As DependencyProperty = DependencyProperty.Register("State"j 
GetType(Boolean)^ GetType(MyStateControl)jNew PropertyMetadata(Raise)) 

End Class 


public class MyAdvancedStateControl : MyStateControl 

{ 

public MyAdvancedStateControl() : base() { } 
static MyAdvancedStateControlO 
{ 

MyStateControl.StateProperty.OverrideMetadata(typeof(MyAdvancedStateControl)j new PropertyMetadata(true)); 

} 

} 


Public Class MyAdvancedStateControl 
Inherits MyStateControl 
Public Sub New() 

MyBase.NewO 
End Sub 

Shared Sub New() 

MyStateControl.StateProperty.OverrideMetadata(GetType(MyAdvancedStateControl), New PropertyMetadata(True)) 
End Sub 
End Class 


See also 

• DependencyProperty 

• Dependency Properties Overview 

• Custom Dependency Properties 

• How-to Topics 
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Windows Presentation Foundation (WPF) introduces routed events that can invoke handlers that exist on various 
listeners in the element tree of an application. 
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Routed Events Overview 
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This topic describes the concept of routed events in Windows Presentation Foundation (WPF). The topic 
defines routed events terminology, describes how routed events are routed through a tree of elements, 
summarizes how you handle routed events, and introduces how to create your own custom routed events. 

Prerequisites 

This topic assumes that you have basic knowledge of the common language runtime (CLR) and object- 
oriented programming, as well as the concept of how the relationships between WPF elements can be 
conceptualized as a tree. In order to follow the examples in this topic, you should also understand Extensible 
Application Markup Language (XAML) and know how to write very basic WPF applications or pages. For more 
information, see Walkthrough: My first WPF desktop application and XAML Overview (WPF). 

What Is a Routed Event? 

You can think about routed events either from a functional or implementation perspective. Both definitions 
are presented here, because some people find one or the other definition more useful. 

Functional definition: A routed event is a type of event that can invoke handlers on multiple listeners in an 
element tree, rather than just on the object that raised the event. 

Implementation definition: A routed event is a CLR event that is backed by an instance of the RoutedEvent 
class and is processed by the Windows Presentation Foundation (WPF) event system. 

A typical WPF application contains many elements. Whether created in code or declared in XAML, these 
elements exist in an element tree relationship to each other. The event route can travel in one of two directions 
depending on the event definition, but generally the route travels from the source element and then "bubbles" 
upward through the element tree until it reaches the element tree root (typically a page or a window). This 
bubbling concept might be familiar to you if you have worked with the DHTML object model previously. 

Consider the following simple element tree: 

<Bor'der Height="50" Width="300" Border'Brush="Gray" BorderThickness="l"> 

<Stacl<Panel Backgr'ound="LightGray" Orientation="Horizontal" Button .Click="CommonClickHandler"> 

<Button Name="YesButton" Width="Auto" >Yes</Button> 

<Button Name="NoButton" Width="Auto" >No</Button> 

<Button Name="CancelButton" Width="Auto" >Cancel</Button> 

</StackPanel> 

</Border> 


This element tree produces something like the following: 



In this simplified element tree, the source of a Click event is one of the Button elements, and whichever Button 
was clicked is the first element that has the opportunity to handle the event. But if no handler attached to the 
Button acts on the event, then the event will bubble upwards to the Button parent in the element tree, which is 
the StackPanel. Potentially, the event bubbles to Border, and then beyond to the page root of the element tree 
(not shown). 
















In other words, the event route for this Click event is: 


Button—>StackPanel—> Border—>... 

Top-level Scenarios for Routed Events 

The following is a brief summary of the scenarios that motivated the routed event concept, and why a typical 
CLR event was not adequate for these scenarios: 

Control composition and encapsulation: Various controls in WPF have a rich content model. For 
example, you can place an image inside of a Button, which effectively extends the visual tree of the button. 
However, the added image must not break the hit-testing behavior that causes a button to respond to a Click 
of its content, even if the user clicks on pixels that are technically part of the image. 

Singular handler attachment points; In Windows Forms, you would have to attach the same handler 
multiple times to process events that could be raised from multiple elements. Routed events enable you to 
attach that handler only once, as was shown in the previous example, and use handler logic to determine 
where the event came from if necessary. For instance, this might be the handler for the previously shown 
XAML: 


private void CommonClickHandler(object sender, RoutedEventArgs e) 
{ 

FrameworkElement feSource = e.Source as FrameworkElement; 
switch (feSource.Name) 

{ 

case "YesButton": 

// do something here ... 
break; 

case "NoButton": 

// do something ... 
break; 

case "CancelButton": 

// do something ... 
break; 

} 

e.Handled=true; 

} 


Private Sub CommonClickHandler(ByVal sender As Object, ByVal e As RoutedEventArgs) 
Dim feSource As FrameworkElement = TryCast(e.Source, FrameworkElement) 

Select Case feSource.Name 
Case "YesButton" 

' do something here ... 

Case "NoButton" 

' do something ... 

Case "CancelButton" 

' do something ... 

End Select 
e.Handled=True 
End Sub 


Class handling: Routed events permit a static handler that is defined by the class. This class handler has the 
opportunity to handle an event before any attached instance handlers can. 

Referencing an event without reflection: Certain code and markup techniques require a way to identify a 
specific event. A routed event creates a RoutedEvent field as an identifier, which provides a robust event 
identification technique that does not require static or run-time reflection. 

How Routed Events Are Implemented 

A routed event is a CLR event that is backed by an instance of the RoutedEvent class and registered with the 



WPF event system. The RoutedEvent instance obtained from registration is typically retained as a public 
static readonly field member of the class that registers and thus "owns" the routed event. The connection 
to the identically named CLR event (which is sometimes termed the "wrapper" event) is accomplished by 
overriding the add and remove implementations for the CLR event. Ordinarily, the add and remove are left 
as an implicit default that uses the appropriate language-specific event syntax for adding and removing 
handlers of that event. The routed event backing and connection mechanism is conceptually similar to how a 
dependency property is a CLR property that is backed by the DependencyProperty class and registered with 
the WPF property system. 

The following example shows the declaration for a custom Tap routed event, including the registration and 
exposure of the RoutedEvent identifier field and the add and remove implementations for the Tap CLR 
event. 


public static readonly RoutedEvent TapEvent = EventManager.RegisterRoutedEvent( 

"Tap"j RoutingStrategy.Bubble^ typeof(RoutedEventHandler), typeof(MyButtonSimple)); 

// Provide CLR accessors for the event 
public event RoutedEventHandler Tap 
{ 

add { AddHandler(TapEventj value); } 
remove { RemoveHandler(TapEvent, value); } 

} 


Public Shared Readonly TapEvent As RoutedEvent = EventManager.RegisterRoutedEvent("Tap", 
RoutingStrategy.Bubble^ GetType(RoutedEventHandler), GetType(MyButtonSimple)) 

' Provide CLR accessors for the event 
Public Custom Event Tap As RoutedEventHandler 

AddHandler(ByVal value As RoutedEventHandler) 

Me.AddHandler(TapEvent, value) 

End AddHandler 

RemoveHandler(ByVal value As RoutedEventHandler) 

Me.RemoveHandler(TapEventj value) 

End RemoveHandler 

RaiseEvent(ByVal sender As Object^ ByVal e As RoutedEventArgs) 

Me.RaiseEvent(e) 

End RaiseEvent 
End Event 


Routed Event Handlers and XAML 

To add a handler for an event using XAML, you declare the event name as an attribute on the element that is 
an event listener. The value of the attribute is the name of your implemented handler method, which must 
exist in the partial class of the code-behind file. 

<Button Click="blSetColor">button</Button> 


The XAML syntax for adding standard CLR event handlers is the same for adding routed event handlers, 
because you are really adding handlers to the CLR event wrapper, which has a routed event implementation 
underneath. For more information about adding event handlers in XAML, see XAML Overview (WPF). 

Routing Strategies 

Routed events use one of three routing strategies: 


• Bubbling: Event handlers on the event source are invoked. The routed event then routes to successive 












parent elennents until reaching the element tree root. Most routed events use the bubbling routing 
strategy. Bubbling routed events are generally used to report input or state changes from distinct 
controls or other Ul elements. 

• Direct: Only the source element itself is given the opportunity to invoke handlers in response. This is 
analogous to the "routing" that Windows Forms uses for events. However, unlike a standard CLR event, 
direct routed events support class handling (class handling is explained in an upcoming section) and 
can be used by EventSetter and EventTrigger. 

• Tunneling: Initially, event handlers at the element tree root are invoked. The routed event then travels 
a route through successive child elements along the route, towards the node element that is the routed 
event source (the element that raised the routed event). Tunneling routed events are often used or 
handled as part of the compositing for a control, such that events from composite parts can be 
deliberately suppressed or replaced by events that are specific to the complete control. Input events 
provided in WPF often come implemented as a tunneling/bubbling pair. Tunneling events are also 
sometimes referred to as Preview events, because of a naming convention that is used for the pairs. 

Why Use Routed Events? 

As an application developer, you do not always need to know or care that the event you are handling is 
implemented as a routed event. Routed events have special behavior, but that behavior is largely invisible if 
you are handling an event on the element where it is raised. 

Where routed events become powerful is if you use any of the suggested scenarios: defining common 
handlers at a common root, compositing your own control, or defining your own custom control class. 

Routed event listeners and routed event sources do not need to share a common event in their hierarchy. Any 
UlElement or ContentElement can be an event listener for any routed event. Therefore, you can use the full set 
of routed events available throughout the working API set as a conceptual "interface" whereby disparate 
elements in the application can exchange event information. This "interface" concept for routed events is 
particularly applicable for input events. 

Routed events can also be used to communicate through the element tree, because the event data for the 
event is perpetuated to each element in the route. One element could change something in the event data, 
and that change would be available to the next element in the route. 

Other than the routing aspect, there are two other reasons that any given WPF event might be implemented 
as a routed event instead of a standard CLR event. If you are implementing your own events, you might also 
consider these principles: 

• Certain WPF styling and templating features such as EventSetter and EventTrigger require the 
referenced event to be a routed event. This is the event identifier scenario mentioned earlier. 

• Routed events support a class handling mechanism whereby the class can specify static methods that 
have the opportunity to handle routed events before any registered instance handlers can access them. 
This is very useful in control design, because your class can enforce event-driven class behaviors that 
cannot be accidentally suppressed by handling an event on an instance. 

Each of the above considerations is discussed in a separate section of this topic. 

Adding and Implementing an Event Handler for a Routed Event 

To add an event handler in XAML, you simply add the event name to an element as an attribute and set the 
attribute value as the name of the event handler that implements an appropriate delegate, as in the following 
example. 


<Button Click="blSetColor">button</Button> 

is the name of the implemented handler that contains the code that handles the Click event, 
must have the same signature as the RoutedEventHandler delegate, which is the event handler 
the Click event. The first parameter of all routed event handler delegates specifies the element to 
which the event handler is added, and the second parameter specifies the data for the event. 

void blSetColor(object senderj RoutedEventArgs args) 

{ 

//logic to handle the Click event 

} 


Private Sub blSetColor(ByVal sender As Object, ByVal args As RoutedEventArgs) 
'logic to handle the Click event 
End Sub 


blSetColor 
blSetColor 
delegate for 


RoutedEventHandler is the basic routed event handler delegate. For routed events that are specialized for 
certain controls or scenarios, the delegates to use for the routed event handlers also might become more 
specialized, so that they can transmit specialized event data. For instance, in a common input scenario, you 
might handle a DragEnter routed event. Your handler should implement the DragEventHandler delegate. By 
using the most specific delegate, you can process the DragEventArgs in the handler and read the Data 
property, which contains the clipboard payload of the drag operation. 

For a complete example of how to add an event handler to an element using XAML, see Handle a Routed 
Event. 

Adding a handler for a routed event in an application that is created in code is straightforward. Routed event 
handlers can always be added through a helper method AddHandler (which is the same method that the 
existing backing calls for add .) However, existing WPF routed events generally have backing implementations 
of add and remove logic that allow the handlers for routed events to be added by a language-specific event 
syntax, which is more intuitive syntax than the helper method. The following is an example usage of the helper 
method: 

void MakeButtonO 
{ 

Button bZ = new Button(); 

bZ.AddHandler(Button.ClickEvent, new RoutedEventHandler(OnbZClick))j 

} 

void OnbZClick(object sender, RoutedEventArgs e) 

{ 

//logic to handle the Click event 

} 


Private Sub MakeButtonO 

Dim bZ As New Button() 

bZ.AddHandler(Button.ClickEvent, New RoutedEventHandler(AddressOf OnbZClick)) 

End Sub 

Private Sub OnbZClick(ByVal sender As Object, ByVal e As RoutedEventArgs) 

'logic to handle the Click event 
End Sub 

The next example shows the C# operator syntax (Visual Basic has slightly different operator syntax because of 
its handling of dereferencing): 








void MakeButton2() 

{ 

Button b2 = new Button(); 

b2.Click += new RoutedEventHandlen(Onb2Click2)j 

} 

void 0nb2Click2(object sender^ RoutedEventArgs e) 

{ 

//logic to handle the Click event 

} 

Private Sub MakeButton2() 

Dim b2 As New Button() 

AddHandler b2.Clicks AddressOf Onb2Click2 
End Sub 

Private Sub 0nb2Click2(ByVal sender As Object, ByVal e As RoutedEventArgs) 

'logic to handle the Click event 
End Sub 

For an example of how to add an event handler in code, see Add an Event Handler Using Code. 

If you are using Visual Basic, you can also use the Handles keyword to add handlers as part of the handler 
declarations. For more information, see Visual Basic and WPF Event Handling. 

The Concept of Handled 

All routed events share a common event data base class, RoutedEventArgs. RoutedEventArgs defines the 
Handled property, which takes a Boolean value. The purpose of the Handled property is to enable any event 
handler along the route to mark the routed event as handled, by setting the value of Handled to true . After 
being processed by the handler at one element along the route, the shared event data is again reported to 
each listener along the route. 

The value of Handled affects how a routed event is reported or processed as it travels further along the route. 
If Handled is true in the event data for a routed event, then handlers that listen for that routed event on 
other elements are generally no longer invoked for that particular event instance. This is true both for 
handlers attached in XAML and for handlers added by language-specific event handler attachment syntaxes 
such as += or Handles . For most common handler scenarios, marking an event as handled by setting 
Handled to true will "stop" routing for either a tunneling route or a bubbling route, and also for any event 
that is handled at a point in the route by a class handler. 

However, there is a "handledEventsToo" mechanism whereby listeners can still run handlers in response to 
routed events where Handled is true in the event data. In other words, the event route is not truly stopped 
by marking the event data as handled. You can only use the handledEventsToo mechanism in code, or in an 
Events etter: 

• In code, instead of using a language-specific event syntax that works for general CLR events, call the 
WPF method AddHandler(RoutedEvent, Delegate, Boolean) to add your handler. Specify the value of 

handledEventsToo as true . 

• In an EventSetter, set the HandledEventsToo attribute to be true . 

In addition to the behavior that Handled state produces in routed events, the concept of Handled has 
implications for how you should design your application and write the event handler code. You can 
conceptualize Handled as being a simple protocol that is exposed by routed events. Exactly how you use this 
protocol is up to you, but the conceptual design for how the value of Handled is intended to be used is as 
follows: 

• If a routed event is marked as handled, then it does not need to be handled again by other elements 
along that route. 










• If a routed event is not marked as handled, then other listeners that were earlier along the route have 
chosen either not to register a handler, or the handlers that were registered chose not to manipulate 
the event data and set Handled to true . (Or, it is of course possible that the current listener is the first 
point in the route.) Handlers on the current listener now have three possible courses of action: 

o Take no action at all; the event remains unhandled, and the event routes to the next listener. 

o Execute code in response to the event, but make the determination that the action taken was not 
substantial enough to warrant marking the event as handled. The event routes to the next 
listener. 

o Execute code in response to the event. Mark the event as handled in the event data passed to the 
handler, because the action taken was deemed substantial enough to warrant marking as 
handled. The event still routes to the next listener, but with Handled= true in its event data, so 
only handiedEventsToo listeners have the opportunity to invoke further handlers. 

This conceptual design is reinforced by the routing behavior mentioned earlier: it is more difficult (although 
still possible in code or styles) to attach handlers for routed events that are invoked even if a previous handler 
along the route has already set Handled to true . 

For more information about Handled, class handling of routed events, and recommendations about when it is 
appropriate to mark a routed event as Handled, see Marking Routed Events as Handled, and Class Handling. 

In applications, it is quite common to just handle a bubbling routed event on the object that raised it, and not 
be concerned with the event's routing characteristics at all. However, it is still a good practice to mark the 
routed event as handled in the event data, to prevent unanticipated side effects just in case an element that is 
further up the element tree also has a handler attached for that same routed event. 

Class Handlers 

If you are defining a class that derives in some way from DependencyObject, you can also define and attach a 
class handler for a routed event that is a declared or inherited event member of your class. Class handlers are 
invoked before any instance listener handlers that are attached to an instance of that class, whenever a routed 
event reaches an element instance in its route. 

Some WPF controls have inherent class handling for certain routed events. This might give the outward 
appearance that the routed event is not ever raised, but in reality it is being class handled, and the routed 
event can potentially still be handled by your instance handlers if you use certain techniques. Also, many base 
classes and controls expose virtual methods that can be used to override class handling behavior. For more 
information both on how to work around undesired class handling and on defining your own class handling 
in a custom class, see Marking Routed Events as Handled, and Class Handling. 

Attached Events in WPF 

The XAML language also defines a special type of event called an attached event An attached event enables 
you to add a handler for a particular event to an arbitrary element. The element handling the event need not 
define or inherit the attached event, and neither the object potentially raising the event nor the destination 
handling instance must define or otherwise "own" that event as a class member. 

The WPF input system uses attached events extensively. However, nearly all of these attached events are 
forwarded through base elements. The input events then appear as equivalent non-attached routed events 
that are members of the base element class. For instance, the underlying attached event Mouse.MouseDown 
can more easily be handled on any given UlElement by using MouseDown on that UlElement rather than 
dealing with attached event syntax either in XAML or code. 






For more information about attached events in WPF, see Attached Events Overview. 


Qualified Event Names in XAML 

Another syntax usage that resembles typename.eventname event syntax but is not strictly speaking 
an attached event usage is when you attach handlers for routed events that are raised by child elements. You 
attach the handlers to a common parent, to take advantage of event routing, even though the common parent 
might not have the relevant routed event as a member. Consider this example again: 

<Bor'der Height="50" Width="300" Border'Brush="Gray" BorderThickness="l"> 

<Stacl<Panel Background="LightGray" Orientation="Horizontal" Button.Click="CommonClickHandler"> 

<Button Name="YesButton" Width="Auto" >Yes</Button> 

<Button Name="NoButton" Width="Auto" >No</Button> 

<Button Name="CancelButton" Width="Auto" >Cancel</Button> 

</StackPanel> 

</Border> 


Here, the parent element listener where the handler is added is a StackPanel. However, it is adding a handler 
for a routed event that was declared and will be raised by the Button class (ButtonBase actually, but available 
to Button through inheritance). Button "owns" the event, but the routed event system permits handlers for any 
routed event to be attached to any UlElement or ContentElement instance listener that could otherwise attach 
listeners for a common language runtime (CLR) event. The default xmlns namespace for these qualified event 
attribute names is typically the default WPF xmlns namespace, but you can also specify prefixed namespaces 
for custom routed events. For more information about xmlns, see XAML Namespaces and Namespace 
Mapping for WPF XAML. 

WPF Input Events 

One frequent application of routed events within the WPF platform is for input events. In WPF, tunneling 
routed events names are prefixed with the word "Preview" by convention. Input events often come in pairs, 
with one being the bubbling event and the other being the tunneling event. For example, the KeyDown event 
and the PreviewKeyDown event have the same signature, with the former being the bubbling input event and 
the latter being the tunneling input event. Occasionally, input events only have a bubbling version, or perhaps 
only a direct routed version. In the documentation, routed event topics cross-reference similar routed events 
with alternative routing strategies if such routed events exist, and sections in the managed reference pages 
clarify the routing strategy of each routed event. 

WPF input events that come in pairs are implemented so that a single user action from input, such as a mouse 
button press, will raise both routed events of the pair in sequence. First, the tunneling event is raised and 
travels its route. Then the bubbling event is raised and travels its route. The two events literally share the same 
event data instance, because the RaiseEvent method call in the implementing class that raises the bubbling 
event listens for the event data from the tunneling event and reuses it in the new raised event. Listeners with 
handlers for the tunneling event have the first opportunity to mark the routed event handled (class handlers 
first, then instance handlers). If an element along the tunneling route marked the routed event as handled, the 
already-handled event data is sent on for the bubbling event, and typical handlers attached for the equivalent 
bubbling input events will not be invoked. To outward appearances it will be as if the handled bubbling event 
has not even been raised. This handling behavior is useful for control compositing, where you might want all 
hit-test based input events or focus-based input events to be reported by your final control, rather than its 
composite parts. The final control element is closer to the root in the compositing, and therefore has the 
opportunity to class handle the tunneling event first and perhaps to "replace" that routed event with a more 
control-specific event, as part of the code that backs the control class. 

As an illustration of how input event processing works, consider the following input event example. In the 
following tree illustration, leaf element #2 is the source of both a PreviewMouseOown and then a MouseOown 




event: 



The order of event processing is as follows: 

1. PreviewMouseDown (tunnel) on root element. 

2. PreviewMouseDown (tunnel) on intermediate element #1. 

3. PreviewMouseDown (tunnel) on source element #2. 

4. MouseDown (bubble) on source element #2. 

5. MouseDown (bubble) on intermediate element #1. 

6. MouseDown (bubble) on root element. 

A routed event handler delegate provides references to two objects: the object that raised the event and the 
object where the handler was invoked. The object where the handler was invoked is the object reported by the 
sender parameter. The object where the event was first raised is reported by the Source property in the event 
data. A routed event can still be raised and handled by the same object, in which case sender and Source are 
identical (this is the case with Steps 3 and 4 in the event processing example list). 

Because of tunneling and bubbling, parent elements receive input events where the Source is one of their 
child elements. When it is important to know what the source element is, you can identify the source element 
by accessing the Source property. 

Usually, once the input event is marked Handled, further handlers are not invoked. Typically, you should mark 
input events as handled as soon as a handler is invoked that addresses your application-specific logical 
handling of the meaning of the input event. 

The exception to this general statement about Handled state is that input event handlers that are registered to 
deliberately ignore Handled state of the event data would still be invoked along either route. For more 
information, see Preview Events or Marking Routed Events as Handled, and Class Handling. 

The shared event data model between tunneling and bubbling events, and the sequential raising of first 
tunneling then bubbling events, is not a concept that is generally true for all routed events. That behavior is 
specifically implemented by how WPF input devices choose to raise and connect the input event pairs. 
Implementing your own input events is an advanced scenario, but you might choose to follow that model for 
your own input events also. 

Certain classes choose to class-handle certain input events, usually with the intent of redefining what a 
particular user-driven input event means within that control and raising a new event. For more information, 
see Marking Routed Events as Handled, and Class Handling. 

For more information on input and how input and events interact in typical application scenarios, see Input 
Overview. 






















EventSetters and EventTriggers 

In styles, you can include some pre-declared XAML event handling syntax in the markup by using an 
EventSetter. When the style is applied, the referenced handler is added to the styled instance. You can declare 
an EventSetter only for a routed event. The following is an example. Note that the bisetcoior method 
referenced here is in a code-behind file. 


<StackPanel 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="SDKSample.Event0vw2" 

Name="dpanel2" 

Initialized="PrimeHandledToo" 

> 

<StackPanel.Resources> 

<Style TargetType="{x:Type Button}"> 

<EventSetter Event="Click" Handler="blSetColor"/> 

</Style> 

</StackPanel.Resources) 

<Button>Click me</Button> 

<Button Name="ThisButton" Click="HandleThis"> 

Raise event, handle it, use handled=true handler to get it anyway. 
</Button> 

</StackPanel> 


The advantage gained here is that the style is likely to contain a great deal of other information that could 
apply to any button in your application, and having the EventSetter be part of that style promotes code reuse 
even at the markup level. Also, an EventSetter abstracts method names for handlers one step further away 
from the general application and page markup. 

Another specialized syntax that combines the routed event and animation features of WPF is an EventTrigger. 
As with EventSetter, only routed events may be used for an EventTrigger. Typically, an EventTrigger is declared 
as part of a style, but an EventTrigger can also be declared on page-level elements as part of the Triggers 
collection, or in a ControlTemplate. An EventTrigger enables you to specify a Storyboard that runs whenever a 
routed event reaches an element in its route that declares an EventTrigger for that event. The advantage of an 
EventTrigger over just handling the event and causing it to start an existing storyboard is that an EventTrigger 
provides better control over the storyboard and its run-time behavior. For more information, see Use Event 
Triggers to Control a Storyboard After It Starts. 

More About Routed Events 

This topic mainly discusses routed events from the perspective of describing the basic concepts and offering 
guidance on how and when to respond to the routed events that are already present in the various base 
elements and controls. However, you can create your own routed event on your custom class along with all 
the necessary support, such as specialized event data classes and delegates. The routed event owner can be 
any class, but routed events must be raised by and handled by UlElement or ContentElement derived classes 
in order to be useful. For more information about custom events, see Create a Custom Routed Event. 

See also 

• EventManager 

• RoutedEvent 

• RoutedEventArgs 

• Marking Routed Events as Handled, and Class Handling 

• Input Overview 

• Commanding Overview 
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• Trees in WPF 

• Weak Event Patterns 
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Extensible Application Markup Language (XAML) defines a language component and type of event called an 
attached event. The concept of an attached event enables you to add a handler for a particular event to an 
arbitrary element rather than to an element that actually defines or inherits the event. In this case, neither the 
object potentially raising the event nor the destination handling instance defines or otherwise "owns" the event. 

Prerequisites 

This topic assumes that you have read Routed Events Overview and XAML Overview (WPF). 

Attached Event Syntax 

Attached events have a XAML syntax and a coding pattern that must be used by the backing code in order to 
support the attached event usage. 

In XAML syntax, the attached event is specified not Just by its event name, but by its owning type plus the event 
name, separated by a dot (.). Because the event name is qualified with the name of its owning type, the attached 
event syntax allows any attached event to be attached to any element that can be instantiated. 

For example, the following is the XAML syntax for attaching a handler for a custom Needscieaning attached event: 

<aqua:Aquarium Name="theAquarium" Height="600" Width="800" aqua:AquariumFilter.NeedsCleaning="WashMe"/> 

Note the aqua: prefix; the prefix is necessary in this case because the attached event is a custom event that comes 
from a custom mapped xmlns. 

How WPF Implements Attached Events 

In WPF, attached events are backed by a RoutedEvent field and are routed through the tree after they are raised. 
Typically, the source of the attached event (the object that raises the event) is a system or service source, and the 
object that runs the code that raises the event is therefore not a direct part of the element tree. 

Scenarios for Attached Events 

In WPF, attached events are present in certain feature areas where there is service-level abstraction, such as for the 
events enabled by the static Mouse class or the Validation class. Classes that interact with or use the service can 
either use the event in the attached event syntax, or they can choose to surface the attached event as a routed 
event that is part of how the class integrates the capabilities of the service. 

Although WPF defines a number of attached events, the scenarios where you will either use or handle the attached 
event directly are very limited. Generally, the attached event serves an architecture purpose, but is then forwarded 
to a non-attached (backed with a CLR event "wrapper") routed event. 

For instance, the underlying attached event Mouse.MouseDown can more easily be handled on any given 
UlElement by using MouseDown on that UlElement rather than dealing with attached event syntax either in XAML 
or code. The attached event serves a purpose in the architecture because it allows for future expansion of input 
devices. The hypothetical device would only need to raise Mouse.MouseDown in order to simulate mouse input, 
and would not need to derive from Mouse to do so. However, this scenario involves code handling of the events. 






and XAML handling of the attached event is not relevant to this scenario. 


Handling an Attached Event in WPF 

The process for handling an attached event, and the handler code that you will write, is basically the same as for a 
routed event. 

In general, a WPF attached event is not very different from a WPF routed event. The differences are how the event 
is sourced and how it is exposed by a class as a member (which also affects the XAML handler syntax). 

Flowever, as noted earlier, the existing WPF attached events are not particularly intended for handling in WPF. More 
often, the purpose of the event is to enable a composited element to report a state to a parent element in 
compositing, in which case the event is usually raised in code and also relies on class handling in the relevant 
parent class. For instance, items within a Selector are expected to raise the attached Selected event, which is then 
class handled by the Selector class and then potentially converted by the Selector class into a different routed 
event, SelectionChanged. For more information on routed events and class handling, see Marking Routed Events 
as Handled, and Class Handling. 

Defining Your Own Attached Events as Routed Events 

If you are deriving from common WPF base classes, you can implement your own attached events by including 
certain pattern methods in your class and by using utility methods that are already present on the base classes. 

The pattern is as follows: 

• A method Add£i'e/7?A/a/77eHandler with two parameters. The first parameter is the instance to which the 
event handler is added. The second parameter is the event handler to add. The method must be public and 

static , with no return value. 

• A method Remove£ve/7fA/ameHandler with two parameters. The first parameter is the instance from 
which the event handler is removed. The second parameter is the event handler to remove. The method 
must be public and static , with no return value. 

The Add£ve/7fA/ameHandler accessor method facilitates XAML processing when attached event handler 
attributes are declared on an element. The Add£ve/7fA/a/77eHandler and Remove£ve/7?A/a/77eHandler methods 
also enable code access to the event handler store for the attached event. 

This general pattern is not yet precise enough for practical implementation in a framework, because any given 
XAML reader implementation might have different schemes for identifying underlying events in the supporting 
language and architecture. This is one of the reasons that WPF implements attached events as routed events; the 
identifier to use for an event (RoutedEvent) is already defined by the WPF event system. Also, routing an event is a 
natural implementation extension on the XAML language-level concept of an attached event. 

The Add£i'e/7fA/ameHandler implementation for a WPF attached event consists of calling the AddHandler with 
the routed event and handler as arguments. 

This implementation strategy and the routed event system in general restrict handling for attached events to either 
UlElement derived classes or ContentElement derived classes, because only those classes have AddHandler 
implementations. 

For example, the following code defines the Needscieaning attached event on the owner class Aquarium , using the 
WPF attached event strategy of declaring the attached event as a routed event. 






public static readonly RoutedEvent NeedsCleaningEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", 

RoutingStrategy.Bubble, typeof(RoutedEventHandler), typeof(AquariumFliter))j 

public static void AddNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler) 

{ 

UIElement uie = d as UIElement; 
if (uie != null) 

{ 

uie.AddHandler(AquariumFilter.NeedsCleaningEvent, handler); 

} 

} 

public static void RemoveNeedsCleaningHandler(DependencyObject d, RoutedEventHandler handler) 

{ 

UIElement uie = d as UIElement; 
if (uie != null) 

{ 

uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler); 

} 


Public Shared Readonly NeedsCleaningEvent As RoutedEvent = EventManager.RegisterRoutedEvent("NeedsCleaning", 
RoutingStrategy.Bubble, GetType(RoutedEventHandler), GetType(AquariumFliter)) 

Public Shared Sub AddNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler) 

Dim uie As UIElement = TryCast(d, UIElement) 

If uie IsNot Nothing Then 

uie.AddHandler(AquariumFliter.NeedsCleaningEvent, handler) 

End If 
End Sub 

Public Shared Sub RemoveNeedsCleaningHandler(ByVal d As DependencyObject, ByVal handler As RoutedEventHandler) 
Dim uie As UIElement = TryCast(d, UIElement) 

If uie IsNot Nothing Then 

uie.RemoveHandler(AquariumFilter.NeedsCleaningEvent, handler) 

End If 
End Sub 


Note that the method used to establish the attached event identifier field, RegisterRoutedEvent, is actually the 
same method that is used to register a non-attached routed event. Attached events and routed events all are 
registered to a centralized internal store. This event store implementation enables the "events as an interface" 
conceptual consideration that is discussed in Routed Events Overview. 

Raising a WPF Attached Event 

You do not typically need to raise existing WPF-defined attached events from your code. These events follow the 
general "service" conceptual model, and service classes such as InputManager are responsible for raising the 
events. 

However, if you are defining a custom attached event based on the WPF model of basing attached events on 
RoutedEvent, you can use RaiseEvent to raise an attached event from any UIElement or ContentElement. Raising a 
routed event (attached or not) requires that you declare a particular element in the element tree as the event 
source; that source is reported as the RaiseEvent caller. Determining which element is reported as the source in the 
tree is your service's responsibility 

See also 

• Routed Events Overview 

• XAML Syntax In Detail 

• XAML and Custom Classes for WPF 
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This topic describes the specific WPF events that signify stages in an object lifetime of creation, use, and 
destruction. 

Prerequisites 

This topic assumes that you understand dependency properties from the perspective of a consumer of existing 
dependency properties on Windows Presentation Foundation (WPF) classes, and have read the Dependency 
Properties Overview topic. In order to follow the examples in this topic, you should also understand Extensible 
Application Markup Language (XAML) (see XAML Overview (WPF)) and know how to write WPF applications. 

Object Lifetime Events 

All objects in Microsoft .NET Framework managed code go through a similar set of stages of life, creation, use, and 
destruction. Many objects also have a finalization stage of life that occurs as part of the destruction phase. WPF 
objects, more specifically the visual objects that WPF identifies as elements, also have a set of common stages of 
object life. The WPF programming and application models expose these stages as a series of events. There are four 
main types of objects in WPF with respect to lifetime events; elements in general, window elements, navigation 
hosts, and application objects. Windows and navigation hosts are also within the larger grouping of visual objects 
(elements). This topic describes the lifetime events that are common to all elements and then introduces the more 
specific ones that apply to application definitions, windows or navigation hosts. 

Common Lifetime Events for Elements 

Any WPF framework-level element (those objects deriving from either FrameworkElement or 
FrameworkContentElement) has three common lifetime events: Initialized, Loaded, and Unloaded. 

I nitialized 

Initialized is raised first, and roughly corresponds to the initialization of the object by the call to its constructor. 
Because the event happens in response to initialization, you are guaranteed that all properties of the object are set. 
(An exception is expression usages such as dynamic resources or binding; these will be unevaluated expressions.) 
As a consequence of the requirement that all properties are set, the sequence of Initialized being raised by nested 
elements that are defined in markup appears to occur in order of deepest elements in the element tree first, then 
parent elements toward the root. This order is because the parent-child relationships and containment are 
properties, and therefore the parent cannot report initialization until the child elements that fill the property are 
also completely initialized. 

When you are writing handlers in response to the Initialized event, you must consider that there is no guarantee 
that all other elements in the element tree (either logical tree or visual tree) around where the handler is attached 
have been created, particularly parent elements. Member variables may be null, or data sources might not yet be 
populated by the underlying binding (even at the expression level). 

Loaded 

Loaded is raised next. The Loaded event is raised before the final rendering, but after the layout system has 
calculated all necessary values for rendering. Loaded entails that the logical tree that an element is contained 
within is complete, and connects to a presentation source that provides the HWND and the rendering surface. 
Standard data binding (binding to local sources, such as other properties or directly defined data sources) will have 
occurred prior to Loaded. Asynchronous data binding (external or dynamic sources) might have occurred, but by 




definition of its asynchronous nature cannot be guaranteed to have occurred. 

The mechanism by which the Loaded event is raised is different than Initialized. The Initialized event is raised 
element by element, without a direct coordination by a completed element tree. By contrast, the Loaded event is 
raised as a coordinated effort throughout the entire element tree (specifically, the logical tree). When all elements 
in the tree are in a state where they are considered loaded, the Loaded event is first raised on the root element. The 
Loaded event is then raised successively on each child element. 


NOTE 

This behavior might superficially resemble tunneling for a routed event. However, no information is carried from event to 
event. Each element always has the opportunity to handle its Loaded event, and marking the event data as handled has no 
effect beyond that element. 


Unloaded 

Unloaded is raised last and is initiated by either the presentation source or the visual parent being removed. When 
Unloaded is raised and handled, the element that is the event source parent (as determined by Parent property) or 
any given element upwards in the logical or visual trees may have already been unset, meaning that data binding, 
resource references, and styles may not be set to their normal or last known run-time value. 

Lifetime Events Application Model Elements 

Building on the common lifetime events for elements are the following application model elements: Application, 
Window, Page, NavigationWindow, and Frame. These extend the common lifetime events with additional events 
that are relevant to their specific purpose. These are discussed in detail in the following locations: 

• Application: Application Management Overview. 

• Window: WPF Windows Overview. 

• Page, NavigationWindow, and Frame: Navigation Overview. 

See also 

• Dependency Property Value Precedence 

• Routed Events Overview 
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Handlers for a routed event can mark the event handled within the event data. Handling the event will effectively 
shorten the route. Class handling is a programming concept that is supported by routed events. A class handler 
has the opportunity to handle a particular routed event at a class level with a handler that is invoked before any 
instance handler on any instance of the class. 

Prerequisites 

This topic elaborates on concepts introduced in the Routed Events Overview. 

When to Mark Events as Handled 

When you set the value of the Handled property to true in the event data for a routed event, this is referred to 
as "marking the event handled". There is no absolute rule for when you should mark routed events as handled, 
either as an application author, or as a control author who responds to existing routed events or implements new 
routed events. For the most part, the concept of "handled" as carried in the routed event's event data should be 
used as a limited protocol for your own application's responses to the various routed events exposed in WPF 
APIs as well as for any custom routed events. Another way to consider the "handled" issue is that you should 
generally mark a routed event handled if your code responded to the routed event in a significant and relatively 
complete way. Typically, there should not be more than one significant response that requires separate handler 
implementations for any single routed event occurrence. If more responses are needed, then the necessary code 
should be implemented through application logic that is chained within a single handler rather than by using the 
routed event system for forwarding. The concept of what is "significant" is also subjective, and depends on your 
application or code. As general guidance, some "significant response" examples include: setting focus, modifying 
public state, setting properties that affect the visual representation, and raising other new events. Examples of 
nonsignificant responses include: modifying private state (with no visual impact, or programmatic 
representation), logging of events, or looking at arguments of an event and choosing not to respond to it. 

The routed event system behavior reinforces this "significant response" model for using handled state of a routed 
event, because handlers added in XAML or the common signature of AddHandler are not invoked in response to 
a routed event where the event data is already marked handled. You must go through the extra effort of adding a 
handler with the handiedEventsToo parameter version (AddHandler(RoutedEvent, Delegate, Boolean)) in order to 
handle routed events that are marked handled by earlier participants in the event route. 

In some circumstances, controls themselves mark certain routed events as handled. A handled routed event 
represents a decision by WPF control authors that the control's actions in response to the routed event are 
significant or complete as part of the control implementation, and the event needs no further handling. Usually 
this is done by adding a class handler for an event, or by overriding one of the class handler virtuals that exist on 
a base class. You can still work around this event handling if necessary; see Working Around Event Suppression 
by Controls later in this topic. 

"Preview" (Tunneling) Events vs. Bubbling Events, and Event Handling 

Preview routed events are events that follow a tunneling route through the element tree. The "Preview" 
expressed in the naming convention is indicative of the general principle for input events that preview 
(tunneling) routed events are raised prior to the equivalent bubbling routed event. Also, input routed events that 






have a tunneling and bubbling pair have a distinct handling logic. If the tunneling/preview routed event is 
marked as handled by an event listener, then the bubbling routed event will be marked handled even before any 
listeners of the bubbling routed event receive it. The tunneling and bubbling routed events are technically 
separate events, but they deliberately share the same instance of event data to enable this behavior. 

The connection between the tunneling and bubbling routed events is accomplished by the internal 
implementation of how any given WPF class raises its own declared routed events, and this is true of the paired 
input routed events. But unless this class-level implementation exists, there is no connection between a tunneling 
routed event and a bubbling routed event that share the naming scheme: without such implementation they 
would be two entirely separate routed events and would not be raised in sequence or share event data. 

For more information about how to implement tunnel/bubble input routed event pairs in a custom class, see 
Create a Custom Routed Event. 

Class Handlers and Instance Handlers 

Routed events consider two different types of listeners to the event: class listeners and instance listeners. Class 
listeners exist because types have called a particular EventManager API ,RegisterClassHandler, in their static 
constructor, or have overridden a class handler virtual method from an element base class. Instance listeners are 
particular class instances/elements where one or more handlers have been attached for that routed event by a 
call to AddFlandler. Existing WPF routed events make calls to AddHandler as part of the common language 
runtime (CLR) event wrapper add{} and removed implementations of the event, which is also how the simple 
XAML mechanism of attaching event handlers via an attribute syntax is enabled. Therefore even the simple XAML 
usage ultimately equates to an AddHandler call. 

Elements within the visual tree are checked for registered handler implementations. Handlers are potentially 
invoked throughout the route, in the order that is inherent in the type of the routing strategy for that routed 
event. For instance, bubbling routed events will first invoke those handlers that are attached to the same element 
that raised the routed event. Then the routed event "bubbles" to the next parent element and so on until the 
application root element is reached. 

From the perspective of the root element in a bubbling route, if class handling or any element closer to the 
source of the routed event invoke handlers that mark the event arguments as being handled, then handlers on 
the root elements are not invoked, and the event route is effectively shortened before reaching that root element. 
However, the route is not completely halted, because handlers can be added using a special conditional that they 
should still be invoked, even if a class handler or instance handler has marked the routed event as handled. This 
is explained in Adding Instance Handlers That Are Raised Even When Events Are Marked Handled, later in this 
topic. 

At a deeper level than the event route, there are also potentially multiple class handlers acting on any given 
instance of a class. This is because the class handling model for routed events enables all possible classes in a 
class hierarchy to each register its own class handler for each routed event. Each class handler is added to an 
internal store, and when the event route for an application is constructed, the class handlers are all added to the 
event route. Class handlers are added to the route such that the most-derived class handler is invoked first, and 
class handlers from each successive base class are invoked next. Generally, class handlers are not registered such 
that they also respond to routed events that were already marked handled. Therefore, this class handling 
mechanism enables one of two choices: 

• Derived classes can supplement the class handling that is inherited from the base class by adding a 
handler that does not mark the routed event handled, because the base class handler will be invoked 
sometime after the derived class handler. 

• Derived classes can replace the class handling from the base class by adding a class handler that marks 
the routed event handled. You should be cautious with this approach, because it will potentially change the 
intended base control design in areas such as visual appearance, state logic, input handling, and command 


handling. 


Class Handling of Routed Events by Control Base Classes 

On each given element node in an event route, class listeners have the opportunity to respond to the routed 
event before any instance listener on the element can. For this reason, class handlers are sometimes used to 
suppress routed events that a particular control class implementation does not wish to propagate further, or to 
provide special handling of that routed event that is a feature of the class. For instance, a class might raise its 
own class-specific event that contains more specifics about what some user input condition means in the context 
of that particular class. The class implementation might then mark the more general routed event as handled. 
Class handlers are typically added such that they are not invoked for routed events where shared event data was 
already marked handled, but for atypical cases there is also a RegisterClassHandlerfType, RoutedEvent, Delegate, 
Boolean) signature that registers class handlers to invoke even when routed events are marked handled. 

Class Handler Virtuals 

Some elements, particularly the base elements such as UlElement, expose empty "On*Event" and 
"OnPreview*Event" virtual methods that correspond to their list of public routed events. These virtual methods 
can be overridden to implement a class handler for that routed event. The base element classes register these 
virtual methods as their class handler for each such routed event using RegisterClassFlandler(Type, RoutedEvent, 
Delegate, Boolean) as described earlier. The On*Event virtual methods make it much simpler to implement class 
handling for the relevant routed events, without requiring special initialization in static constructors for each 
type. For instance, you can add class handling for the DragEnter event in any UlElement derived class by 
overriding the OnDragEnter virtual method. Within the override, you could handle the routed event, raise other 
events, initiate class-specific logic that might change element properties on instances, or any combination of 
those actions. You should generally call the base implementation in such overrides even if you mark the event 
handled. Calling the base implementation is strongly recommended because the virtual method is on the base 
class. The standard protected virtual pattern of calling the base implementations from each virtual essentially 
replaces and parallels a similar mechanism that is native to routed event class handling, whereby class handlers 
for all classes in a class hierarchy are called on any given instance, starting with the most-derived class' handler 
and continuing to the base class handler. You should only omit the base implementation call if your class has a 
deliberate requirement to change the base class handling logic. Whether you call the base implementation 
before or after your overriding code will depend on the nature of your implementation. 

Input Event Class Handling 

The class handler virtual methods are all registered such that they are only invoked in cases where any shared 
event data are not already marked handled. Also, for the input events uniquely, the tunneling and bubbling 
versions typically are raised in sequence and share event data. This entails that for a given pair of class handlers 
of input events where one is the tunneling version and the other is the bubbling version, you may not want to 
mark the event handled immediately. If you implement the tunneling class handling virtual method to mark the 
event handled, that will prevent the bubbling class handler from being invoked (as well as preventing any 
normally registered instance handlers for either the tunneling or bubbling event from being invoked). 

Once class handling on a node is complete, the instance listeners are considered. 

Adding Instance Handlers That Are Raised Even When Events Are 
Marked Handled 

The AddHandler method supplies a particular overload that allows you to add handlers that will be invoked by 
the event system whenever an event reaches the handling element in the route, even if some other handler has 
already adjusted the event data to mark that event as handled. This is not typically done. Generally, handlers can 
be written to adjust all areas of application code that might be influenced by an event, regardless of where it was 
handled in an element tree, even if multiple end results are desired. Also, typically there is really only one 
element that needs to respond to that event, and the appropriate application logic had already happened. But the 


handiedEventsToo overload is available for the exceptional cases where some other element in an element tree or 
control compositing has already marked an event as handled, but other elements either higher or lower in the 
element tree (depending on route) still wish to have their own handlers invoked. 

When to Mark Handled Events as Unhandled 

Generally, routed events that are marked handled should not be marked unhandled (Handled set back to false ) 
even by handlers that act on handiedEventsToo . However, some input events have high-level and lower-level 
event representations that can overlap when the high-level event is seen at one position in the tree and the low- 
level event at another position. For instance, consider the case where a child element listens to a high-level key 
event such as Textinput while a parent element listens to a low-level event such as KeyDown. If the parent 
element handles the low-level event, the higher-level event can be suppressed even in the child element that 
intuitively should have first opportunity to handle the event. 

In these situations it may be necessary to add handlers to both parent elements and child elements for the low- 
level event. The child element handler implementation can mark the low-level event as handled, but the parent 
element handler implementation would set it unhandled again so that further elements up the tree (as well as 
the high-level event) can have the opportunity to respond. This situation is should be fairly rare. 

Deliberately Suppressing Input Events for Control Compositing 

The main scenario where class handling of routed events is used is for input events and composited controls. A 
composited control is by definition composed of multiple practical controls or control base classes. Often the 
author of the control wishes to amalgamate all of the possible input events that each of the subcomponents 
might raise, in order to report the entire control as the singular event source. In some cases the control author 
might wish to suppress the events from components entirely, or substitute a component-defined event that 
carries more information or implies a more specific behavior. The canonical example that is immediately visible 
to any component author is how a Windows Presentation Foundation (WPF) Button handles any mouse event 
that will eventually resolve to the intuitive event that all buttons have: a Click event. 

The Button base class (ButtonBase) derives from Control which in turn derives from FrameworkElement and 
UlElement, and much of the event infrastructure needed for control input processing is available at the UlElement 
level. In particular, UlElement processes general Mouse events that handle hit testing for the mouse cursor within 
its bounds, and provides distinct events for the most common button actions, such as MouseLeftButtonDown. 
UlElement also provides an empty virtual On MouseLeftButtonDown as the preregistered class handler for 
MouseLeftButtonDown, and ButtonBase overrides it. Similarly, ButtonBase uses class handlers for 
MouseLeftButtonUp. In the overrides, which are passed the event data, the implementations mark that 
RoutedEventArgs instance as handled by setting Handled to true , and that same event data is what continues 
along the remainder of the route to other class handlers and also to instance handlers or event setters. Also, the 
OnMouseLeftButtonUp override will next raise the Click event. The end result for most listeners will be that the 
MouseLeftButtonDown and MouseLeftButtonUp events "disappear" and are replaced instead by Click, an event 
that holds more meaning because it is known that this event originated from a true button and not some 
composite piece of the button or from some other element entirely. 

Working Around Event Suppression by Controls 

Sometimes this event suppression behavior within individual controls can interfere with some more general 
intentions of event handling logic for your application. For instance, if for some reason your application had a 
handler for MouseLeftButtonDown located at the application root element, you would notice that any mouse 
click on a button would not invoke MouseLeftButtonDown or MouseLeftButtonUp handlers at the root level. The 
event itself actually did bubble up (again, event routes are not truly ended, but the routed event system changes 
their handler invocation behavior after being marked handled). When the routed event reached the button, the 
ButtonBase class handling marked the MouseLeftButtonDown handled because it wished to substitute the Click 
event with more meaning. Therefore, any standard MouseLeftButtonDown handler further up the route would 
not be invoked. There are two techniques you can use to ensure that your handlers would be invoked in this 
circumstance. 




The first technique is to deliberately add the handler using the handiedEventsToo signature of 
AddHandlerfRoutedEvent, Delegate, Boolean). A limitation of this approach is that this technique for attaching an 
event handler is only possible from code, not from markup. The simple syntax of specifying the event handler 
name as an event attribute value via Extensible Application Markup Language (XAML) does not enable that 
behavior. 

The second technique works only for input events, where the tunneling and bubbling versions of the routed 
event are paired. For these routed events, you can add handlers to the preview/tunneling equivalent routed event 
instead. That routed event will tunnel through the route starting from the root, so the button class handling code 
would not intercept it, presuming that you attached the Preview handler at some ancestor element level in the 
application's element tree. If you use this approach, be cautious about marking any Preview event handled. For 
the example given with PreviewMouseLeftButtonDown being handled at the root element, if you marked the 
event as Handled in the handler implementation, you would actually suppress the Click event. That is typically 
not desirable behavior. 

See also 

• EventManager 

• Preview Events 

• Create a Custom Routed Event 

• Routed Events Overview 
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Preview events, also known as tunneling events, are routed events where the direction of the route travels from 
the application root towards the element that raised the event and is reported as the source in event data. Not all 
event scenarios support or require preview events; this topic describes the situations where preview events exist, 
how applications or components should handle them, and cases where creating preview events in custom 
components or classes might be appropriate. 

Preview Events and Input 

When you handle Preview events in general, be cautious about marking the events handled in the event data. 
Handling a Preview event on any element other than the element that raised it (the element that is reported as the 
source in the event data) has the effect of not providing an element the opportunity to handle the event that it 
originated. Sometimes this is the desired result, particularly if the elements in question exist in relationships within 
the compositing of a control. 

For input events specifically. Preview events also share event data instances with the equivalent bubbling event. If 
you use a Preview event class handler to mark the input event handled, the bubbling input event class handler will 
not be invoked. Or, if you use a Preview event instance handler to mark the event handled, handlers for the 
bubbling event will not typically be invoked. Class handlers or instance handlers can be registered or attached with 
an option to be invoked even if the event is marked handled, but that technique is not commonly used. 

For more information about class handling and how it relates to Preview events see Marking Routed Events as 
Handled, and Class Handling. 

Working Around Event Suppression by Controls 

One scenario where Preview events are commonly used is for composited control handling of input events. 
Sometimes, the author of the control suppresses a certain event from originating from their control, perhaps in 
order to substitute a component-defined event that carries more information or implies a more specific behavior. 
For instance, a Windows Presentation Foundation (WPF) Button suppresses MouseLeftButtonDown and 
MouseRightButtonDown bubbling events raised by the Button or its composite elements in favor of capturing the 
mouse and raising a Click event that is always raised by the Button itself The event and its data still continue along 
the route, but because the Button marks the event data as Handled, only handlers for the event that specifically 
indicated they should act in the handiedEventsToo case are invoked. If other elements towards the root of your 
application still wanted an opportunity to handle a control-suppressed event, one alternative is to attach handlers 
in code with handiedEventsToo specified as true . But often a simpler technique is to change the routing direction 
you handle to be the Preview equivalent of an input event. For instance, if a control suppresses 
MouseLeftButtonDown, try attaching a handler for PreviewMouseLeftButtonDown instead. This technique only 
works for base element input events such as MouseLeftButtonDown. These input events use tunnel/bubble pairs, 
raise both events, and share the event data. 

Each of these techniques has either side effects or limitations. The side effect of handling the Preview event is that 
handling the event at that point might disable handlers that expect to handle the bubbling event, and therefore the 
limitation is that it is usually not a good idea to mark the event handled while it is still on the Preview part of the 
route. The limitation of the handiedEventsToo technique is that you cannot specify a handiedEventsToo handler in 
XAML as an attribute, you must register the event handler in code after obtaining an object reference to the 
element where the handler is to be attached. 


See also 








Marking Routed Events as Handled, and Class Handling 
Routed Events Overview 
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Windows Presentation Foundation (WPF) defines several events that are raised in response to a change in the 
value of a property. Often the property is a dependency property. The event itself is sometimes a routed event and 
is sometimes a standard common language runtime (CLR) event The definition of the event varies depending on 
the scenario, because some property changes are more appropriately routed through an element tree, whereas 
other property changes are generally only of concern to the object where the property changed. 

Identifying a Property Change Event 

Not all events that report a property change are explicitly identified as a property changed event, either by virtue 
of a signature pattern or a naming pattern. Generally, the description of the event in the SDK documentation 
indicates whether the event is directly tied to a property value change and provides cross-references between the 
property and event. 

RoutedPropertyChanged Events 

Certain events use an event data type and delegate that are explicitly used for property change events. The event 
data type is RoutedPropertyChangedEventArgs<T>, and the delegate is RoutedPropertyChangedEventHandler<T>. 
The event data and delegate both have a generic type parameter that is used to specify the actual type of the 
changing property when you define the handler. The event data contains two properties, OldValue and NewValue, 
which are both then passed as the type argument in the event data. 

The "Routed" part of the name indicates that the property changed event is registered as a routed event. The 
advantage of routing a property changed event is that the top level of a control can receive property changed 
events if properties on the child elements (the control's composite parts) change values. For instance, you might 
create a control that incorporates a RangeBase control such as a Slider. If the value of the Value property changes 
on the slider part, you might want to handle that change on the parent control rather than on the part. 

Because you have an old value and a new value, it might be tempting to use this event handler as a validator for 
the property value. However, that is not the design intention of most property changed events. Generally, the 
values are provided so that you can act on those values in other logic areas of your code, but actually changing the 
values from within the event handler is not advisable, and may cause unintentional recursion depending on how 
your handler is implemented. 

If your property is a custom dependency property, or if you are working with a derived class where you have 
defined the instantiation code, there is a much better mechanism for tracking property changes that is built in to 
the WPF property system: the property system callbacks CoerceValueCallback and PropertyChangedCallback. For 
more details about how you can use the WPF property system for validation and coercion, see Dependency 
Property Callbacks and Validation and Custom Dependency Properties. 

DependencyPropertyChanged Events 

Another pair of types that are part of a property changed event scenario is 

DependencyPropertyChangedEventArgs and DependencyPropertyChangedEventHandler. Events for these 
property changes are not routed; they are standard CLR events. DependencyPropertyChangedEventArgs is an 
unusual event data reporting type because it does not derive from EventArgs; 
DependencyPropertyChangedEventArgs is a structure, not a class. 

Events that use DependencyPropertyChangedEventArgs and DependencyPropertyChangedEventHandler are 
slightly more common than RoutedPropertyChanged events. An example of an event that uses these types is 
IsMouseCapturedChanged. 





Like RoutedPropertyChangedEventArgs<T>, DependencyPropertyChangedEventArgs also reports an old and new 
value for the property. Also, the same considerations about what you can do with the values apply; it is generally 
not recommended that you attempt to change the values again on the sender in response to the event. 

Property Triggers 

A closely related concept to a property changed event is a property trigger. A property trigger is created within a 
style or template and enables you to create a conditional behavior based on the value of the property where the 
property trigger is assigned. 

The property for a property trigger must be a dependency property. It can be (and frequently is) a read-only 
dependency property. A good indicator for when a dependency property exposed by a control is at least partially 
designed to be a property trigger is if the property name begins with "Is". Properties that have this naming are 
often a read-only Boolean dependency property where the primary scenario for the property is reporting control 
state that might have consequences to the real-time Ul and is thus a property trigger candidate. 

Some of these properties also have a dedicated property changed event. For instance, the property 
IsMouseCaptured has a property changed event IsMouseCapturedChanged. The property itself is read-only, with 
its value adjusted by the input system, and the input system raises IsMouseCapturedChanged on each real-time 
change. 

Compared to a true property changed event, using a property trigger to act on a property change has some 
limitations. 

Property triggers work through an exact match logic. You specify a property and a value that indicates the specific 
value for which the trigger will act. For instance: <Setter Property="IsMouseCaptured" Value="true"> ... </Setter> . 
Because of this limitation, the majority of property trigger usages will be for Boolean properties, or properties that 
take a dedicated enumeration value, where the possible value range is manageable enough to define a trigger for 
each case. Or property triggers might exist only for special values, such as when an items count reaches zero, and 
there would be no trigger that accounts for the cases when the property value changes away from zero again 
(instead of triggers for all cases, you might need a code event handler here, or a default behavior that toggles back 
from the trigger state again when the value is nonzero). 

The property trigger syntax is analogous to an "if" statement in programming. If the trigger condition is true, then 
the "body" of the property trigger is "executed". The "body" of a property trigger is not code, it is markup. That 
markup is limited to using one or more Setter elements to set other properties of the object where the style or 
template is being applied. 

To offset the "if" condition of a property trigger that has a wide variety of possible values, it is generally advisable 
to set that same property value to a default by using a Setter. This way, the Trigger contained setter will have 
precedence when the trigger condition is true, and the Setter that is not within a Trigger will have precedence 
whenever the trigger condition is false. 

Property triggers are generally appropriate for scenarios where one or more appearance properties should 
change, based on the state of another property on the same element. 

To learn more about property triggers, see Styling and Templating. 

See also 

• Routed Events Overview 

• Dependency Properties Overview 
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For the Microsoft Visual Basic .NET language specifically, you can use the language-specific Handles keyword to 
associate event handlers with instances, instead of attaching event handlers with attributes or using the 
AddHandler method. However, the Handles technique for attaching handlers to instances does have some 
limitations, because the Handles syntax cannot support some of the specific routed event features of the WPF 
event system. 

Using "Handles" in a WPF Application 

The event handlers that are connected to instances and events with Handles must all be defined within the partial 
class declaration of the instance, which is also a requirement for event handlers that are assigned through attribute 
values on elements. You can only specify Handles for an element on the page that has a Name property value (or 
x:Name Directive declared). This is because the Name in XAML creates the instance reference that is necessary to 
support the /rrsfa/ice.fverif reference format required by the Handles syntax. The only element that can be used 
for Handles without a Name reference is the root-element instance that defines the partial class. 

You can assign the same handler to multiple elements by separating lnstance.Event'ce^e'cer\ces after Handles with 
commas. 

You can use Handies to assign more than one handler to the same Instance.Eventceie’cence. Do not assign any 
importance to the order in which handlers are given in the Handles reference; you should assume that handlers 
that handle the same event can be invoked in any order. 

To remove a handler that was added with Handles in the declaration, you can call RemoveHandler. 

You can use Handies to attach handlers for routed events, so long as you attach handlers to instances that define 
the event being handled in their members tables. For routed events, handlers that are attached with Handles 
follow the same routing rules as do handlers that are attached as XAML attributes, or with the common signature 
of AddHandler. This means that if the event is already marked handled (the Handled property in the event data is 
True ), then handlers attached with Handles are not invoked in response to that event instance. The event could 
be marked handled by instance handlers on another element in the route, or by class handling either on the 
current element or earlier elements along the route. For input events that support paired tunnel/bubble events, the 
tunneling route may have marked the event pair handled. For more information about routed events, see Routed 
Events Overview. 

Limitations of "Handles" for Adding Handlers 

Handles cannot reference handlers for attached events. You must use the add accessor method for that attached 
event, or typename.eventnameevent attributes in XAML. For details, see Routed Events Overview. 

For routed events, you can only use Handles to assign handlers for instances where that event exists in the 
instance members table. However, with routed events in general, a parent element can be a listener for an event 
from child elements, even if the parent element does not have that event in its members table. In attribute syntax, 
you can specify this through a typename.membernamestXubute form that qualifies which type actually defines the 
event you want to handle. For instance, a parent Page (with no Click event defined) can listen for button-click 
events by assigning an attribute handler in the form Button.Click . But Handles does not support the 
typename.membernametoxm, because it must support a conflicting Instance-Eventtom. For details, see Routed 
Events Overview. 


























Handles cannot attach handlers that are invoked for events that are already marked handled. Instead, you must 
use code and call the handiedEventsToo overload of AddHandler(RoutedEvent, Delegate, Boolean). 


NOTE 

Do not use the Handles syntax in Visual Basic code when you specify an event handler for the same event in XAML. In this 
case, the event handler is called twice. 


How WPF Implements "Handles" Functionality 

When a Extensible Application Markup Language (XAML) page is compiled, the intermediate file declares Friend 
withEvents references to every element on the page that has a Name property set (or x:Name Directive declared). 
Each named instance is potentially an element that can be assigned to a handler through Handles . 


NOTE 

Within Visual Studio, IntelliSense can show you completion for which elements are available for a Handles reference in a 
page. However, this might take one compile pass so that the intermediate file can populate all the Friends references. 


See also 

• AddHandler 

• Marking Routed Events as Handled, and Class Handling 

• Routed Events Overview 

• XAML Overview (WPF) 
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In applications, it is possible that handlers that are attached to event sources will not be destroyed in coordination 
with the listener object that attached the handler to the source. This situation can lead to memory leaks. Windows 
Presentation Foundation (WPF) introduces a design pattern that can be used to address this issue, by providing a 
dedicated manager class for particular events and implementing an interface on listeners for that event. This 
design pattern is known as the weak event pattern. 

Why Implement the Weak Event Pattern? 

Listening for events can lead to memory leaks. The typical technique for listening to an event is to use the 
language-specific syntax that attaches a handler to an event on a source. For example, in C#, that syntax is: 

source.SomeEvent += new SomeEventHandler(MyEventHandler) . 

This technique creates a strong reference from the event source to the event listener. Ordinarily, attaching an event 
handler for a listener causes the listener to have an object lifetime that is influenced by the object lifetime of the 
source (unless the event handler is explicitly removed). But in certain circumstances, you might want the object 
lifetime of the listener to be controlled by other factors, such as whether it currently belongs to the visual tree of 
the application, and not by the lifetime of the source. Whenever the source object lifetime extends beyond the 
object lifetime of the listener, the normal event pattern leads to a memory leak: the listener is kept alive longer 
than intended. 

The weak event pattern is designed to solve this memory leak problem. The weak event pattern can be used 
whenever a listener needs to register for an event, but the listener does not explicitly know when to unregister. The 
weak event pattern can also be used whenever the object lifetime of the source exceeds the useful object lifetime 
of the listener. (In this case, usefur\s determined by you.) The weak event pattern allows the listener to register for 
and receive the event without affecting the object lifetime characteristics of the listener in any way. In effect, the 
implied reference from the source does not determine whether the listener is eligible for garbage collection. The 
reference is a weak reference, thus the naming of the weak event pattern and the related APIs. The listener can be 
garbage collected or otherwise destroyed, and the source can continue without retaining noncollectible handler 
references to a now destroyed object. 

Who Should Implement the Weak Event Pattern? 

Implementing the weak event pattern is interesting primarily for control authors. As a control author, you are 
largely responsible for the behavior and containment of your control and the impact it has on applications in 
which it is inserted. This includes the control object lifetime behavior, in particular the handling of the described 
memory leak problem. 

Certain scenarios inherently lend themselves to the application of the weak event pattern. One such scenario is 
data binding. In data binding, it is common for the source object to be completely independent of the listener 
object, which is a target of a binding. Many aspects of WPF data binding already have the weak event pattern 
applied in how the events are implemented. 

How to Implement the Weak Event Pattern 

There are three ways to implement weak event pattern. The following table lists the three approaches and provides 
some guidance for when you should use each. 





APPROACH WHEN TO IMPLEMENT 

Use an existing weak event manager class If the event you want to subscribe to has a corresponding 

WeakEventManager, use the existing weak event manager. For 
a list of weak event managers that are included with WPF, see 
the inheritance hierarchy in the WeakEventManager class. 
Because the included weak event managers are limited, you 
will probably need to choose one of the other approaches. 


Use a generic weak event manager class Use a generic 

WeakEventManager<TEventSource,TEventArgs> when an 
existing WeakEventManager is not available, you want an easy 
way to implement, and you are not concerned about 
efficiency. The generic 

WeakEventManager<TEventSource,TEventArgs> is less 
efficient than an existing or custom weak event manager. For 
example, the generic class does more reflection to discover the 
event given the event's name. Also, the code to register the 
event by using the generic 

WeakEventManager<TEventSource,TEventArgs> is more 
verbose than using an existing or custom 
WeakEventManager. 


Create a custom weak event manager class Create a custom WeakEventManager when an existing 

WeakEventManager is not available and you want the best 
efficiency. Using a custom WeakEventManager to subscribe to 
an event will be more efficient, but you do incur the cost of 
writing more code at the beginning. 


Use a third-party weak event manager NuGet has several weak event managers and many WPF 

frameworks also support the pattern (for instance, see Prism's 
documentation on loosely coupled event subscription). 

The following sections describe how to implement the weak event pattern. For purposes of this discussion, the 
event to subscribe to has the following characteristics. 



Using an Existing Weak Event Manager Class 

1. Find an existing weak event manager. 

For a list of weak event managers that are included with WPF, see the inheritance hierarchy in the 
WeakEventManager class. 

2. Use the new weak event manager instead of the normal event hookup. 

For example, if your code uses the following pattern to subscribe to an event: 

source.SomeEvent += new SomeEventEventHandler(OnSomeEvent); 


Change it to the following pattern: 







SomeEventWeakEventManagen.AddHandler(sourcej OnSomeEvent); 

Similarly, if your code uses the following pattern to unsubscribe from an event: 

source.SomeEvent new SomeEventEventHandler(OnSomeEvent); 

Change it to the following pattern: 

SomeEventWeakEventManager.RemoveHandler(source, OnSomeEvent); 

Using the Generic Weak Event Manager Class 

1. Use the generic WeakEventManager<TEventSource,TEventArgs> class instead of the normal event hookup. 

When you use WeakEventManager<TEventSource,TEventArgs> to register event listeners, you supply the 
event source and EventArgs type as the type parameters to the class and call AddHandler as shown in the 
following code: 

WeakEventManagercEventSourcOj SomeEventEventArgs>.AddHandler(sourcej "SomeEvent", source_SomeEvent); 


Creating a Custom Weak Event Manager Class 

1. Copy the following class template to your project. 

This class inherits from the WeakEventManager class. 

class SomeEventWeakEventManager : WeakEventManager 

{ 


private SomeEventWeakEventManager() 

{ 

} 

III <summary> 

III Add a handler for the given source's event. 

Ill </summary> 

public static void AddHandler(EventSource source, 

EventHandler<SomeEventEventArgs> handler) 

{ 

if (source == null) 

throw new ArgumentNullException("source"); 
if (handler == null) 

throw new ArgumentNullException("handler"); 

CurrentManager.ProtectedAddHandler(source, handler); 

} 

III <summary> 

III Remove a handler for the given source's event. 

Ill </summary> 

public static void RemoveHandler(EventSource source, 

EventHandler<SomeEventEventArgs> handler) 

{ 

if (source == null) 

throw new ArgumentNullException("source")j 
if (handler == null) 

throw new ArgumentNullException("handler"); 


} 


CurrentManager.ProtectedRemoveHandler(source, handler); 






Ill <summar'y> 

III Get the event manager for the current thread. 

Ill </summary> 

private static SomeEventWeakEventManager CurrentManager 

{ 

get 

{ 

Type managerType = typeof(SomeEventWeakEventManager); 
SomeEventWeakEventManager manager = 

(SomeEventWeakEventManager)GetCurrentManager(managerType); 

// at first use, create and register a new manager 
if (manager == null) 

{ 

manager = new SomeEventWeakEventManager(); 

SetCurrentManager(managerType, manager); 

} 

return manager; 

} 

} 

III <summary> 

III Return a new list to hold listeners to the event. 

Ill </summary> 

protected override ListenerList NewListenerList() 

{ 

return new ListenerList<SomeEventEventArgs>(); 

} 

III <summary> 

III Listen to the given source for the event. 

Ill </summary> 

protected override void StartListening(object source) 

{ 

EventSource typedSource = (EventSource)source; 

typedSource.SomeEvent += new EventHandler<SomeEventEventArgs>(OnSomeEvent); 

} 

III <summary> 

III Stop listening to the given source for the event. 

Ill </summary> 

protected override void StopListening(object source) 

{ 

EventSource typedSource = (EventSource)source; 

typedSource.SomeEvent -= new EventHandler<SomeEventEventArgs>(OnSomeEvent); 

} 

III <summary> 

III Event handler for the SomeEvent event. 

Ill </summary> 

void OnSomeEvent(object sender, SomeEventEventArgs e) 

{ 

DeliverEvent(sender, e); 

} 


2. Replace the SomeEventWeakEventManager name with your own name. 

3. Replace the three names described previously with the corresponding names for your event. ( SomeEvent , 

EventSource , and SomeEventEventArgs ) 

4. Set the visibility (public / internal / private) of the weak event manager class to the same visibility as event it 
manages. 


5. Use the new weak event manager instead of the normal event hookup. 





For example, if your code uses the following pattern to subscribe to an event: 


source.SomeEvent += new SomeEventEventHandler(OnSomeEvent); 


Change it to the following pattern: 


SomeEventWeakEventManager.AddHandler(sourcej OnSomeEvent)j 


Similarly, if your code uses the following pattern to unsubscribe to an event: 
source.SomeEvent new SomeEventEventHandler(OnSome); 


Change it to the following pattern: 


SomeEventWeakEventManager.RemoveHandler(source, OnSomeEvent); 


See also 

• WeakEventManager 

• IWeakEventListener 

• Routed Events Overview 

• Data Binding Overview 
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The topics in this section describe how to use events in WPF. 

In This Section 

Add an Event Handler Using Code 

Handle a Routed Event 

Create a Custom Routed Event 

Find the Source Element in an Event Handler 

Add Class Handling for a Routed Event 

Reference 

Routed Event 

EventManager 

RoutingStrategy 

Related Sections 
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This example shows how to add an event handler to an element by using code. 

If you want to add an event handler to a XAML element, and the markup page that contains the element has 
already been loaded, you must add the handler using code. Alternatively, if you are building up the element tree for 
an application entirely using code and not declaring any elements using XAML, you can call specific methods to 
add event handlers to the constructed element tree. 

Example 

The following example adds a new Button to an existing page that is initially defined in XAML. A code-behind file 
implements an event handler method and then adds that method as a new event handler on the Button. 

The C# example uses the += operator to assign a handler to an event. This is the same operator that is used to 
assign a handler in the common language runtime (CLR) event handling model. Microsoft Visual Basic does not 
support this operator as a means of adding event handlers. It instead requires one of two techniques: 

• Use the AddHandler method, together with an AddressOf operator, to reference the event handler 
implementation. 

• Use the Handles keyword as part of the event handler definition. This technique is not shown here; See 
Visual Basic and WPF Event Handling. 


sTextBlock Name="textl">Start by clicking the button below</TextBlock> 

<Button Name="bl" Click="MakeButton">Make new button and add handler to it</Button> 


public partial class RoutedEventAddRemoveHandler { 
void MakeButton(object sender^ RoutedEventArgs e) 

{ 

Button b2 = new Button(); 
b2.Content = "New Button"; 

// Associate event handler to the button. You can remove the event 

// handler using syntax rather than "+=". 

b2.Click += new RoutedEventHandler(0nb2Click); 

root.Children.Insert(root.Children.Countj b2); 

DockPanel.SetDock(b2, Dock.Top); 

textl.Text = "Now click the second button..."; 

bl.IsEnabled = false; 

} 

void 0nb2Click(object sender^ RoutedEventArgs e) 

{ 

textl.Text = "New Button (b2) Was Clicked!!"; 

} 








Public Partial Class RoutedEventAddRemoveHandler 

Private Sub MakeButton(ByVal sender As Object, ByVal e As RoutedEventArgs) 
Dim b2 As Button = New Button() 
b2.Content = "New Button" 

Addhlandler b2.Click, AddressOf 0nb2Click 
root.Children.Insert(root.Children.Count, b2) 

DockPanel.SetDock(b2, Dock.Top) 
textl.Text = "Now click the second button..." 
bl.IsEnabled = False 
End Sub 

Private Sub 0nb2Click(By\/al sender As Object, ByVal e As RoutedEventArgs) 
textl.Text = "New Button (b2) Was Clicked!!" 

End Sub 


NOTE 

Adding an event handler in the initially parsed XAML page is much simpler. Within the object element where you want to 
add the event handler, add an attribute that matches the name of the event that you want to handle. Then specify the value 
of that attribute as the name of the event handler method that you defined in the code-behind file of the XAML page. For 
more information, see XAML Overview (WPF) or Routed Events Overview. 


See also 

• Routed Events Overview 

• How-to Topics 




How to: Handle a Routed Event 
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This example shows how bubbling events work and how to write a handler that can process the routed event data. 

Example 

In Windows Presentation Foundation (WPF), elements are arranged in an element tree structure. The parent 
element can participate in the handling of events that are initially raised by child elements in the element tree. This 
is possible because of event routing. 

Routed events typically follow one of two routing strategies, bubbling or tunneling. This example focuses on the 
bubbling event and uses the ButtonBase.Click event to show how routing works. 

The following example creates two Button controls and uses XAML attribute syntax to attach an event handler to a 
common parent element, which in this example is StackPanel. Instead of attaching individual event handlers for 
each Button child element, the example uses attribute syntax to attach the event handler to the StackPanel parent 
element. This event-handling pattern shows how to use event routing as a technique for reducing the number of 
elements where a handler is attached. All the bubbling events for each Button route through the parent element. 

Note that on the parent StackPanel element, the Click event name specified as the attribute is partially qualified by 
naming the Button class. The Button class is a ButtonBase derived class that has the Click event in its members 
listing. This partial qualification technique for attaching an event handler is necessary if the event that is being 
handled does not exist in the members listing of the element where the routed event handler is attached. 

<Stacl<Panel 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="SDKSample.RoutedEventHandle" 

Name="dpanel" 

Button.Clicl<="HandleClick" 

> 

cStackPanel.Resources> 

<Style TargetType="{x:Type Button}"> 

<Setter Property="Height" Value="20"/> 

<Setter Property="Width" Value="250"/> 

<Setter Property="HorizontalAlignment" Value="Left"/> 

</Style> 

</StackPanel.Resources> 

<Button Name="Buttonl">Item l</Button> 

<Button Name="Button2">Item 2</Button> 
cTextBlock Name="results"/> 

</StackPanel> 


The following example handles the Click event. The example reports which element handles the event and which 
element raises the event. The event handler is executed when the user clicks either button. 





public partial class RoutedEventHandle : StackPanel 

{ 

StringBuilder eventstr = new StringBuilder()j 

void HandleClick(object sender, RoutedEventArgs args) 

{ 

// Get the element that handled the event. 

FrameworkElement fe = (FrameworkElement)senderj 
eventstr.Append("Event handled by element named ")j 
eventstr.Append(fe.Name); 
eventstr.Append("\n"); 

// Get the element that raised the event. 

FrameworkElement fe2 = (FrameworkElement)args.Source; 

eventstr.Append("Event originated from source element of type "); 

eventstr. Append (args. Source. GetTypeO .ToStringO); 

eventstr.Append(" with Name "); 

eventstr.Append(fe2.Name); 

eventstr.Append("\n"); 

// Get the routing strategy. 

eventstr.Append("Event used routing strategy "); 
eventstr.Append(args.RoutedEvent.RoutingStrategy); 
eventstr.Append("\n"); 

results.Text = eventstr.ToStringO; 

} 

} 


Private eventstr As New Text.StringBuilder() 


Private Sub HandleClick(ByVal sender As Object, ByVal args As RoutedEventArgs) 

' Get the element that handled the event. 

Dim fe As FrameworkElement = DirectCast(sender, FrameworkElement) 
eventstr.Append("Event handled by element named ") 
event str.Append(fe.Name) 
eventstr.Append(vbLf) 

' Get the element that raised the event. 

Dim fe2 As FrameworkElement = DirectCast(args.Source, 
eventstr.Append("Event originated from source element 
eventstr. Append (args. Source. [GetType] () .ToStringO) 
eventstr.Append(" with Name ") 
eventstr.Append(fe2.Name) 
eventstr.Append(vbLf) 

FrameworkElement) 
of type ") 

' Get the routing strategy. 

eventstr.Append("Event used routing strategy ") 
eventstr.Append(args.RoutedEvent.RoutingStrategy) 
eventstr.Append(vbLf) 


results.Text = eventstr.ToStringO 

End Sub 



See also 

• RoutedEvent 

• Input Overview 

• Routed Events Overview 

• How-to Topics 

• XAML Syntax In Detail 
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For your custom event to support event routing, you need to register a RoutedEvent using the 
RegisterRoutedEvent method. This example demonstrates the basics of creating a custom routed event. 

Example 

As shown in the following example, you first register a RoutedEvent using the RegisterRoutedEvent method. By 
convention, the RoutedEvent static field name should end with the suffix Event. In this example, the name of the 
event is Tap and the routing strategy of the event is Bubble. After the registration call, you can provide add-and- 
remove common language runtime (CLR) event accessors for the event. 

Note that even though the event is raised through the oniap virtual method in this particular example, how you 
raise your event or how your event responds to changes depends on your needs. 

Note also that this example basically implements an entire subclass of Button; that subclass is built as a separate 
assembly and then instantiated as a custom class on a separate Extensible Application Markup Language (XAML) 
page. This is to illustrate the concept that subclassed controls can be inserted into trees composed of other 
controls, and that in this situation, custom events on these controls have the very same event routing capabilities 
as any native Windows Presentation Foundation (WPF) element does. 

public class MyButtonSimple: Button 
{ 

// Create a custom routed event by first registering a RoutedEventID 
// This event uses the bubbling routing strategy 

public static readonly RoutedEvent TapEvent = EventManager.RegisterRoutedEvent( 

"Tap"j RoutingStrategy.Bubble^ typeof(RoutedEventHandler), typeof(MyButtonSimple))j 

// Provide CLR accessors for the event 
public event RoutedEventHandler Tap 
{ 

add { AddHandler(TapEventj value); } 
remove { RemoveHandler(TapEvent, value); } 

} 

// This method raises the Tap event 
void RaiseTapEventO 
{ 

RoutedEventArgs newEventArgs = new RoutedEventArgs(MyButtonSimple.TapEvent); 
RaiseEvent(newEventArgs); 

} 

// For demonstration purposes we raise the event when the MyButtonSimple is clicked 
protected override void OnClick() 

{ 

RaiseTapEventO; 

} 

} 







Public Class MyButtonSimple 
Inherits Button 

' Create a custom routed event by first registering a RoutedEventID 
' This event uses the bubbling routing strategy 

Public Shared Readonly TapEvent As RoutedEvent = EventManager.RegisterRoutedEvent("Tap", 
RoutingStrategy.Bubble^ GetType(RoutedEventHandler), GetType(MyButtonSimple)) 

' Provide CLR accessors for the event 
Public Custom Event Tap As RoutedEventHandler 

AddHandler(ByVal value As RoutedEventHandler) 

Me.AddHandler(TapEvent^ value) 

End AddHandler 

RemoveHandler(By\/al value As RoutedEventHandler) 

Me.RemoveHandler(TapEventj value) 

End RemoveHandler 

RaiseEvent(ByVal sender As Object^ ByVal e As RoutedEventArgs) 

Me.RaiseEvent(e) 

End RaiseEvent 
End Event 

' This method raises the Tap event 
Private Sub RaiseTapEvent() 

Dim newEventArgs As New RoutedEventArgs(MyButtonSimple.TapEvent) 

MyBase.RaiseEvent(newEventArgs) 

End Sub 

' For demonstration purposes we raise the event when the MyButtonSimple is clicked 
Protected Overrides Sub OnClick() 

Me.RaiseTapEventO 
End Sub 

End Class 


<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
xmlns:custom="clr-namespace:SDKSample;assembly=SDKSampleLibrary" 
x:Class="SDKSample.RoutedEventCustomApp" 

> 

<Window.Resources> 

<Style TargetType="{x:Type custom:MyButtonSimple}"> 

<Setter Property="Height" \/alue="20"/> 

<Setter Property="Width" Value="250"/> 

<Setter Property="HorizontalAlignment" Value="Left"/> 

<Setter Property="Background" \/alue="#808080"/> 

</Style> 

</Window.Resources> 

<StackPanel Background="LightGray"> 

<custom:MyButtonSimple Name="mybtnsimple" Tap="TapHandler">Click to see Tap custom event 
work</custom:MyButtonSimple> 

</StackPanel> 

</Window> 


Tunneling events are created the same way, but with RoutingStrategy set to Tunnel in the registration call. By 
convention, tunneling events in WPF are prefixed with the word "Preview". 

To see an example of how bubbling events work, see Handle a Routed Event. 


See also 



Routed Events Overview 

Input Overview 

Control Authoring Overview 
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This example shows how to find the source element in an event handler. 

Example 

The following example shows a Click event handler that is declared in a code-behind file. When a user clicks the 
button that the handler is attached to, the handler changes a property value. The handler code uses the Source 
property of the routed event data that is reported in the event arguments to change the Width property value on 
the Source element. 


<Button Click="HandleClicl<">Button l</Button> 


void HandleClick(object sender^ RoutedEventArgs e) 

{ 

// You must cast the sender object as a Button elementj or at least as FrameworkElement, to set Width 
Button srcButton = e.Source as Button; 
srcButton.Width = 200; 

} 


Private Sub HandleClick(ByVal sender As Object^ ByVal e As RoutedEventArgs) 

'You must cast the object as a Button element, or at least as FrameworkElement, to set Width 
Dim srcButton As Button 
srcButton = CType(e.Source, Button) 
srcButton.Width = 200 
End Sub 


See also 

• RoutedEventArgs 

• Routed Events Overview 

• How-to Topics 
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Routed events can be handled either by class handlers or instance handlers on any given node in the route. Class 
handlers are invoked first, and can be used by class implementations to suppress events from instance handling or 
introduce other event specific behaviors on events that are owned by base classes. This example illustrates two 
closely related techniques for implementing class handlers. 

Example 

This example uses a custom class based on the Canvas panel. The basic premise of the application is that the 
custom class introduces behaviors on its child elements, including intercepting any left mouse button clicks and 
marking them handled, before the child element class or any instance handlers on it will be invoked. 

The UlElement class exposes a virtual method that enables class handling on the PreviewMouseLeftButtonDown 
event, by simply overriding the event. This is the simplest way to implement class handling if such a virtual method 
is available somewhere in your class' hierarchy. The following code shows the OnPreviewMouseLeftButtonDown 
implementation in the "MyEditContainer" that is derived from Canvas. The implementation marks the event as 
handled in the arguments, and then adds some code to give the source element a basic visible change. 

protected override void OnPreviewMouseRightButtonDown(System.Windows.Input.MouseButtonEventArgs e) 

{ 

e.Handled = true; //suppress the click event and other leftmousebuttondown responders 
MyEditContainer ec = (MyEditContainer)e.Source; 
if (ec.EditState) 

{ ec.EditState = false; } 
else 

{ ec.EditState = true; } 
base.OnPreviewMouseRightButtonDown(e); 

} 


Protected Overrides Sub OnPreviewHouseRightButtonDown(ByVal e As System.Windows.Input.MouseButtonEventArgs) 
e.Handled = True 'suppress the click event and other leftmousebuttondown responders 
Dim ec As MyEditContainer = CType(e.Sourcej MyEditContainer) 

If ec.EditState Then 

ec.EditState = False 

Else 

ec.EditState = True 
End If 

MyBase.OnPreviewMouseRightButtonDown(e) 

End Sub 


If no virtual is available on base classes or for that particular method, class handling can be added directly using a 
utility method of the EventManager class, RegisterClassHandler. This method should only be called within the static 
initialization of classes that are adding class handling. This example adds another handler for 
PreviewMouseLeftButtonDown , and in this case the registered class is the custom class. In contrast, when using the 
virtuals, the registered class is really the UlElement base class. In cases where base classes and subclass each 
register class handling, the subclass handlers are invoked first. The behavior in an application would be that first 
this handler would show its message box and then the visual change in the virtual method's handler would be 
shown. 





static MyEditContainerO 

{ 

EventManagen.RegisterClassHandler(typeof(MyEditContainer)j PreviewMouseRightButtonDownEventj new 
RoutedEventElandlen(LocalOnMouseRightButtonDown)) j 
} 

internal static void LocalOnMouseRightButtonDown(object sendetj RoutedEventArgs e) 

{ 

MessageBox.Show("this is invoked before the On* class handler on UIElement")j 

//e.Handled = true; //uncommenting this would cause ONLY the subclass' class handler to respond 

} 


Shared Sub New() 

EventManager.RegisterClassHandler(GetType(MyEditContainer)j PreviewMouseRightButtonDownEventj New 
RoutedEventHandler(AddressOf LocalOnMouseRightButtonDown)) 

End Sub 

Friend Shared Sub LocalOnMouseRightButtonDown(ByVal sender As Object^ ByVal e As RoutedEventArgs) 
MessageBox.Show("this is invoked before the On* class handler on UIElement") 

'e.Handled = True //uncommenting this would cause ONLY the subclass' class handler to respond 
End Sub 


See also 

• EventManager 

• Marking Routed Events as Handled, and Class Handling 

• Handle a Routed Event 

• Routed Events Overview 
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Windows Presentation Foundation (WPF) includes support for several types of input. This input includes text, 
touch, mouse, commands, focus, touch, drag-and-drop, and digital ink. This section describes topics related to 
input in WPF. 

In This Section 

Input Overview 
Commanding Overview 
Focus Overview 

Styling for Focus in Controls, and FocusVisualStyle 
Walkthrough: Creating Your First Touch Application 
How-to Topics 
Digital Ink 

Reference 

UlElement 

FrameworkElement 

ContentElement 

FrameworkContentElement 

Keyboard 

Mouse 

FocusManager 

Related Sections 

Controls 

Events 




Input Overview 
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The Windows Presentation Foundation (WPF) subsystem provides a powerful API for obtaining input from a 
variety of devices, including the mouse, keyboard, touch, and stylus. This topic describes the services provided 
by WPF and explains the architecture of the input systems. 

Input API 

The primary input API exposure is found on the base element classes: UlElement, ContentElement, 
FrameworkElement, and FrameworkContentElement. For more information about the base elements, see Base 
Elements Overview. These classes provide functionality for input events related to key presses, mouse buttons, 
mouse wheel, mouse movement, focus management, and mouse capture, to name a few. By placing the input 
API on the base elements, rather than treating all input events as a service, the input architecture enables the 
input events to be sourced by a particular object in the Ul, and to support an event routing scheme whereby 
more than one element has an opportunity to handle an input event. Many input events have a pair of events 
associated with them. For example, the key down event is associated with the KeyDown and PreviewKeyDown 
events. The difference in these events is in how they are routed to the target element. Preview events tunnel 
down the element tree from the root element to the target element. Bubbling events bubble up from the target 
element to the root element. Event routing in WPF is discussed in more detail later in this overview and in the 
Routed Events Overview. 

Keyboard and Mouse Classes 

In addition to the input API on the base element classes, the Keyboard class and Mouse classes provide 
additional API for working with keyboard and mouse input. 

Examples of input API on the Keyboard class are the Modifiers property, which returns the ModifierKeys 
currently pressed, and the IsKeyDown method, which determines whether a specified key is pressed. 

The following example uses the GetKeyStates method to determine if a Key is in the down state. 

// Uses the Keyboard.GetKeyStates to determine if a key is down. 

// A bitwise AND operation is used in the comparison. 

// e is an instance of KeyEventArgs. 

if ((Keyboard.GetKeyStates(Key.Return) & KeyStates.Down) > 0) 

{ 

btnNone.Background = Brushes.Red; 

} 


' Uses the Keyboard.GetKeyStates to determine if a key is down. 

' A bitwise AND operation is used in the comparison. 

' e is an instance of KeyEventArgs. 

If (Keyboard.GetKeyStates(Key.Return) And KeyStates.Down) > 0 Then 
btnNone.Background = Brushes.Red 

Examples of input API on the Mouse class are MiddleButton, which obtains the state of the middle mouse 
button, and DirectlyOver, which gets the element the mouse pointer is currently over. 

The following example determines whether the LeftButton on the mouse is in the Pressed state. 





if (Mouse.LeftButton == MouseButtonState.Pressed) 

{ 

UpdateSampleResults("Left Button Pressed"); 

} 

If Mouse.LeftButton = MouseButtonState.Pressed Then 
UpdateSampleResults("Left Button Pressed") 

End If 

The Mouse and Keyboard classes are covered in more detail throughout this overview. 

Stylus Input 

WPF has integrated support for the Stylus. The Stylus is a pen input made popular by the Tablet PC. WPF 
applications can treat the stylus as a mouse by using the mouse API, but WPF also exposes a stylus device 
abstraction that use a model similar to the keyboard and mouse. All stylus-related APIs contain the word 
"Stylus". 

Because the stylus can act as a mouse, applications that support only mouse input can still obtain some level of 
stylus support automatically. When the stylus is used in such a manner, the application is given the opportunity 
to handle the appropriate stylus event and then handles the corresponding mouse event. In addition, higher- 
level services such as ink input are also available through the stylus device abstraction. For more information 
about ink as input, see Getting Started with Ink. 

Event Routing 

A FrameworkElement can contain other elements as child elements in its content model, forming a tree of 
elements. In WPF, the parent element can participate in input directed to its child elements or other descendants 
by handing events. This is especially useful for building controls out of smaller controls, a process known as 
"control composition" or "compositing." For more information about element trees and how element trees relate 
to event routes, see Trees in WPF. 

Event routing is the process of forwarding events to multiple elements, so that a particular object or element 
along the route can choose to offer a significant response (through handling) to an event that might have been 
sourced by a different element. Routed events use one of three routing mechanisms: direct, bubbling, and 
tunneling. In direct routing, the source element is the only element notified, and the event is not routed to any 
other elements. However, the direct routed event still offers some additional capabilities that are only present for 
routed events as opposed to standard CLR events. Bubbling works up the element tree by first notifying the 
element that sourced the event, then the parent element, and so on. Tunneling starts at the root of the element 
tree and works down, ending with the original source element. For more information about routed events, see 
Routed Events Overview. 

WPF input events generally come in pairs that consists of a tunneling event and a bubbling event. Tunneling 
events are distinguished from bubbling events with the "Preview" prefix. For instance, PreviewMouseMove is the 
tunneling version of a mouse move event and MouseMove is the bubbling version of this event. This event 
pairing is a convention that is implemented at the element level and is not an inherent capability of the WPF 
event system. For details, see the WPF Input Events section in Routed Events Overview. 

Handling Input Events 

To receive input on an element, an event handler must be associated with that particular event. In XAML this is 
straightforward: you reference the name of the event as an attribute of the element that will be listening for this 
event. Then, you set the value of the attribute to the name of the event handler that you define, based on a 
delegate. The event handler must be written in code such as C# and can be included in a code-behind file. 



Keyboard events occur when the operating system reports key actions that occur while keyboard focus is on an 
element. Mouse and stylus events each fall into two categories: events that report changes in pointer position 
relative to the element, and events that report changes in the state of device buttons. 

Keyboard Input Event Example 

The following example listens for a left arrow key press. A StackPanel is created that has a Button. An event 
handler to listen for the left arrow key press is attached to the Button instance. 

The first section of the example creates the StackPanel and the Button and attaches the event handler for the 
KeyDown. 

<StackPanel> 

<Button Background="AliceBlue" 

KeyDown="OnButtonKeyDown" 

Content="Buttonl"/> 

</StackPanel> 


// Create the UI elements. 

StackPanel keyboardStackPanel = new StackPanel(); 

Button keyboardButtonl = new Button(); 

// Set properties on Buttons. 
keyboardButtonl.Background = Brushes.AliceBlue; 
keyboardButtonl.Content = "Button 1"; 

// Attach Buttons to StackPanel. 

keyboardStackPanel.Children.Add(keyboardButtonl); 

// Attach event handler. 

keyboardButtonl.KeyDown += new KeyEventHandler(OnButtonKeyDown)j 


' Create the UI elements. 

Dim keyboardStackPanel As New StackPanel() 

Dim keyboardButtonl As New Button() 

' Set properties on Buttons. 

keyboardButtonl.Background = Brushes.AliceBlue 
keyboardButtonl.Content = "Button 1" 

' Attach Buttons to StackPanel. 

keyboardStackPanel.Children.Add(keyboardButtonl) 

' Attach event handler. 

AddHandler keyboardButtonl.KeyDownj AddressOf OnButtonKeyDown 


The second section is written in code and defines the event handler. When the left arrow key is pressed and the 
Button has keyboard focus, the handler runs and the Background color of the Button is changed. If the key is 
pressed, but it is not the left arrow key, the Background color of the Button is changed back to its starting color. 



private void OnButtonKeyDown(object sender, KeyEventArgs e) 

{ 

Button source = e.Source as Button; 
if (source != null) 

{ 

if (e.Key == Key.Left) 

{ 

source.Background = Brushes.LemonChiffon; 

} 

else 

{ 

source.Background = Brushes.AliceBlue; 

} 

} 

} 


Private Suh OnButtonKeyDown(ByVal sender As Object, ByVal e As KeyEventArgs) 
Dim source As Button = TryCast(e.Source, Button) 

If source IsNot Nothing Then 
If e.Key = Key.Left Then 

source.Background = Brushes.LemonChiffon 

Else 

source.Background = Brushes.AliceBlue 
End If 
End If 
End Sub 


Mouse Input Event Example 

In the following example, the Background color of a Button is changed when the mouse pointer enters the 
Button. The Background color is restored when the mouse leaves the Button. 

The first section of the example creates the StackPanel and the Button control and attaches the event handlers 
for the MouseEnter and MouseLeave events to the Button. 


<StackPanel> 

<Button Background="AliceBlue" 

MouseEnter="OnMouseExampleMouseEnter" 

MouseLeave="OnMosueExampleMouseLeave">Button 

</Button> 

</StackPanel> 


// Create the UI elements. 

StackPanel mouseMoveStackPanel = new StackPanel(); 

Button mouseMoveButton = new Button(); 

// Set properties on Button. 

mouseMoveButton.Background = Brushes.AliceBlue; 
mouseMoveButton.Content = "Button"; 

// Attach Buttons to StackPanel. 
mouseMoveStackPanel.Children.Add(mouseMoveButton); 

// Attach event handler. 

mouseMoveButton.MouseEnter += new MouseEventHandler(OnMouseExampleMouseEnter); 
mouseMoveButton.MouseLeave += new MouseEventHandler(OnMosueExampleMouseLeave); 




' Create the UI elements. 

Dim mouseMoveStackPanel As New StackPanel() 

Dim mouseMoveButton As New Button() 

' Set properties on Button. 

mouseMoveButton.Background = Brushes.AliceBlue 
mouseMoveButton.Content = "Button" 

' Attach Buttons to StackPanel. 

mouseMoveStackPanel.Children.Add(mouseMoveButton) 

' Attach event handler. 

AddHandler mouseMoveButton.MouseEnter^ AddressOf OnMouseExampleMouseEnter 
AddHandler mouseMoveButton.MouseLeave^ AddressOf OnMosueExampleMouseLeave 


The second section of the example is written in code and defines the event handlers. When the mouse enters the 
Button, the Background color of the Button is changed to SlateGray. When the mouse leaves the Button, the 
Background color of the Button is changed back to AliceBlue. 

private void OnMouseExampleMouseEnter(object sender^ MouseEventArgs e) 

{ 

// Cast the source of the event to a Button. 

Button source = e.Source as Button; 

//If source is a Button, 
if (source != null) 

{ 

source.Background = Brushes.SlateGray; 

} 

} 


Private Sub OnMouseExampleMouseEnter(ByVal sender As Object^ ByVal e As MouseEventArgs) 
' Cast the source of the event to a Button. 

Dim source As Button = TryCast(e.Sourcej Button) 

' If source is a Button. 

If source IsNot Nothing Then 

source.Background = Brushes.SlateGray 
End If 
End Sub 


private void OnMosueExampleMouseLeave(object sender^ MouseEventArgs e) 

{ 

// Cast the source of the event to a Button. 

Button source = e.Source as Button; 

// If source is a Button, 
if (source != null) 

{ 

} 

} 


source.Background = Brushes.AliceBlue; 




Private Sub OnMosueExampleMouseLeave(By\/al sender As Object^ ByVal e As MouseEventArgs) 
' Cast the source of the event to a Button. 

Dim source As Button = TryCast(e.Sourcej Button) 

' If source is a Button. 

If source IsNot Mothing Then 

source.Background = Brushes.AliceBlue 
End If 
End Sub 


Text Input 

The Textinput event enables you to listen for text input in a device-independent manner. The keyboard is the 
primary means of text input, but speech, handwriting, and other input devices can generate text input also. 

For keyboard input, WPF first sends the appropriate KeyDown/KeyUp events. If those events are not handled 
and the key is textual (rather than a control key such as directional arrows or function keys), then a Textinput 
event is raised. There is not always a simple one-to-one mapping between KeyDown/KeyUp and Textinput 
events because multiple keystrokes can generate a single character of text input and single keystrokes can 
generate multi-character strings. This is especially true for languages such as Chinese, Japanese, and Korean 
which use Input Method Editors (IMEs) to generate the thousands of possible characters in their corresponding 
alphabets. 

When WPF sends a KeyUp/KeyDown event. Key is set to Key.System if the keystrokes could become part of a 
Textinput event (if ALT+S is pressed, for example). This allows code in a KeyDown event handler to check for 
Key.System and, if found, leave processing for the handler of the subsequently raised Textinput event. In these 
cases, the various properties of the TextCompositionEventArgs argument can be used to determine the original 
keystrokes. Similarly, if an IME is active. Key has the value of Key.lmeProcessed, and ImeProcessedKey gives the 
original keystroke or keystrokes. 

The following example defines a handler for the Click event and a handler for the KeyDown event. 

The first segment of code or markup creates the user interface. 

<StackPanel KeyDown="OnTextInputKeyDown"> 

<Button Click="OnTextInputButtonClick" 

Content="Open" /> 

<TextBox> . . . </TextBox> 

</StackPanel> 


// Create the UI elements. 

StackPanel textInputStackPanel = new StackPanel(); 

Button textInputeButton = new Button(); 

TextBox textlnputlextBox = new TextBox(); 
textInputeButton.Content = "Open"; 

// Attach elements to StackPanel. 
textInputStackPanel.Children.Add(textInputeButton); 
textInputStackPanel.Children.Add(textlnputlextBox); 

// Attach event handlers. 

textInputStackPanel.KeyDown += new KeyEventHandler(OnTextlnputKeyDown); 
textInputeButton.Click += new RoutedEventHandler(OnTextlnputButtonCllck); 




' Create the UI elements. 

Dim textInputStackPanel As New StackPanel() 

Dim textInputeButton As New Button() 

Dim textInputTextBox As New TextBox() 
textInputeButton.Content = "Open" 

' Attach elements to StackPanel. 

textInputStackPanel.Children.Add(textInputeButton) 
textInputStackPanel.Children.Add(textInputTextBox) 

' Attach event handlers. 

AddHandler textInputStackPanel.KeyDown^ AddressOf OnlextlnputKeyDown 
AddHandler textInputeButton.Clicks AddressOf OnTextInputButtonClick 


The second segment of code contains the event handlers. 

private void OnTextInputKeyDown(object sender^ KeyEventArgs e) 

{ 

if (e.Key == Key.O && Keyboard.Modifiers == ModifierKeys.Control) 

{ 

handleO; 
e.Handled = true; 

} 

} 

private void OnTextInputButtonClick(object sender^ RoutedEventArgs e) 

{ 

handleO; 
e.Handled = true; 

} 

public void handle() 

{ 

MessageBox.Show("Pretend this opens a file"); 

} 


Private Sub OnTextInputKeyDown(ByVal sender As Object^ ByVal e As KeyEventArgs) 

If e.Key = Key.O AndAlso Keyboard.Modifiers = ModifierKeys.Control Then 
handleO 

e.Handled = True 
End If 
End Sub 

Private Sub OnTextInputButtonClick(ByVal sender As Object^ ByVal e As RoutedEventArgs) 
handleO 

e.Handled = True 
End Sub 

Public Sub handleO 

MessageBox.Show("Pretend this opens a file") 

End Sub 


Because input events bubble up the event route, the StackPanel receives the input regardless of which element 
has keyboard focus. The TextBox control is notified first and the onTextinputKeyDown handler is called only if the 
TextBox did not handle the input. If the PreviewKeyDown event is used instead of the KeyDown event, the 
OnTextinputKeyDown handler is called first. 

In this example, the handling logic is written two times—one time for CTRL+0, and again for button's click event. 
This can be simplified by using commands, instead of handling the input events directly. Commands are 
discussed in this overview and in Commanding Overview. 






Touch and Manipulation 

New hardware and API in the Windows 7 operating system provide applications the ability to receive input from 
multiple touches simultaneously. WPF enables applications to detect and respond to touch in a manner similar 
to responding to other input, such as the mouse or keyboard, by raising events when touch occurs. 

WPF exposes two types of events when touch occurs: touch events and manipulation events. Touch events 
provide raw data about each finger on a touchscreen and its movement. Manipulation events interpret the input 
as certain actions. Both types of events are discussed in this section. 

Prerequisites 

You need the following components to develop an application that responds to touch. 

• Visual Studio 2010. 

• Windows 7. 

• A device, such as a touchscreen, that supports Windows Touch. 

Terminology 

The following terms are used when touch is discussed. 

• Touch is a type of user input that is recognized by Windows 7. Usually, touch is initiated by putting 
fingers on a touch-sensitive screen. Note that devices such as a touchpad that is common on laptop 
computers do not support touch if the device merely converts the finger's position and movement as 
mouse input. 

• Multitouch is touch that occurs from more than one point simultaneously. Windows 7 and WPF 
supports multitouch. Whenever touch is discussed in the documentation for WPF, the concepts apply to 
multitouch. 

• A manipulation occurs when touch is interpreted as a physical action that is applied to an object. In WPF, 
manipulation events interpret input as a translation, expansion, or rotation manipulation. 

• A touch device represents a device that produces touch input, such as a single finger on a touchscreen. 

Controls that Respond to Touch 

The following controls can be scrolled by dragging a finger across the control if it has content that is scrolled out 
of view. 

• ComboBox 

• ContextMenu 

• DataGrid 

• ListBox 

• ListView 

• Menultem 

• TextBox 

• Tool Bar 

• TreeView 

The ScrollViewer defines the ScrollViewer.PanningMode attached property that enables you to specify whether 
touch panning is enabled horizontally, vertically, both, or neither. The ScrollViewer.PanningDeceleration property 
specifies how quickly the scrolling slows down when the user lifts the finger from the touchscreen. The 



ScrollViewer.PanningRatio attached property specifies the ratio of scrolling offset to translate manipulation 
offset. 

Touch Events 

The base classes, UlElement, UlElementBD, and ContentElement, define events that you can subscribe to so your 
application will respond to touch. Touch events are useful when your application interprets touch as something 
other than manipulating an object. For example, an application that enables a user to draw with one or more 
fingers would subscribe to touch events. 

All three classes define the following events, which behave similarly, regardless of the defining class. 

• TouchDown 

• TouchMove 

• TouchUp 

• TouchEnter 

• TouchLeave 

• PreviewTouchDown 

• PreviewTouchMove 

• PreviewTouchUp 

• GotTouchCapture 

• LostTouchCapture 

Like keyboard and mouse events, the touch events are routed events. The events that begin with Preview are 
tunneling events and the events that begin with Touch are bubbling events. For more information about routed 
events, see Routed Events Overview. When you handle these events, you can get the position of the input, 
relative to any element, by calling the GetTouchPoint or GetIntermediateTouchPoints method. 

To understand the interaction among the touch events, consider the scenario where a user puts one finger on an 
element, moves the finger in the element, and then lifts the finger from the element. The following illustration 
shows the execution of the bubbling events (the tunneling events are omitted for simplicity). 
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Touch events 


The following list describes the sequence of the events in the preceding illustration. 

1. The TouchEnter event occurs one time when the user puts a finger on the element. 

2. The TouchDown event occurs one time. 

3. The TouchMove event occurs multiple times as the user moves the finger within the element. 

4. The TouchUp event occurs one time when the user lifts the finger from the element. 


5. The TouchLeave event occurs one time. 












When more than two fingers are used, the events occur for each finger. 

Manipulation Events 

For cases where an application enables a user to manipulate an object, the UlElement class defines manipulation 
events. Unlike the touch events that simply report the position of touch, the manipulation events report how the 
input can be interpreted. There are three types of manipulations, translation, expansion, and rotation. The 
following list describes how to invoke the three types of manipulations. 

• Put a finger on an object and move the finger across the touchscreen to invoke a translation 
manipulation. This usually moves the object. 

• Put two fingers on an object and move the fingers closer together or farther apart from one another to 
invoke an expansion manipulation. This usually resizes the object. 

• Put two fingers on an object and rotate the fingers around each other to invoke a rotation manipulation. 

This usually rotates the object. 

More than one type of manipulation can occur simultaneously. 

When you cause objects to respond to manipulations, you can have the object appear to have inertia. This can 
make your objects simulate the physical world. For example, when you push a book across a table, if you push 
hard enough the book will continue to move after you release it. WPF enables you to simulate this behavior by 
raising manipulation events after the user's fingers releases the object. 

For information about how to create an application that enables the user to move, resize, and rotate an object, 
see Walkthrough: Creating Your First Touch Application. 

The UlElement defines the following manipulation events. 

• ManipulationStarting 

• ManipulationStarted 

• ManipulationDelta 

• ManipulationInertiaStarting 

• ManipulationCompleted 

• ManipulationBoundaryFeedback 

By default, a UlElement does not receive these manipulation events. To receive manipulation events on a 
UlElement, set UlElement.lsManipulationEnabled to true . 

The Execution Path of Manipulation Events 

Consider a scenario where a user "throws" an object. The user puts a finger on the object, moves the finger 
across the touchscreen for a short distance, and then lifts the finger while it is moving. The result of this is that 
the object will move under the user's finger and continue to move after the user lifts the finger. 

The following illustration shows the execution path of manipulation events and important information about 
each event. 
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Manipulation events 

The following list describes the sequence of the events in the preceding illustration. 


1. The ManipulationStarting event occurs when the user places a finger on the object. Among other things, 
this event allows you to set the ManipulationContainer property. In the subsequent events, the position of 
the manipulation will be relative to the ManipulationContainer. In events other than 
ManipulationStarting, this property is read-only, so the ManipulationStarting event is the only time that 
you can set this property. 


2. The ManipulationStarted event occurs next. This event reports the origin of the manipulation. 

3. The ManipulationDelta event occurs multiple times as a user's fingers move on a touchscreen. The 
DeltaManipulation property of the ManipulationDeltaEventArgs class reports whether the manipulation 
is interpreted as movement, expansion, or translation. This is where you perform most of the work of 
manipulating an object. 

4. The ManipulationInertiaStarting event occurs when the user's fingers lose contact with the object. This 
event enables you to specify the deceleration of the manipulations during inertia. This is so your object 
can emulate different physical spaces or attributes if you choose. For example, suppose your application 
has two objects that represent items in the physical world, and one is heavier than the other. You can 
make the heavier object decelerate faster than the lighter object. 


5. The ManipulationDelta event occurs multiple times as inertia occurs. Note that this event occurs when the 
user's fingers move across the touchscreen and when WPF simulates inertia. In other words, 
ManipulationDelta occurs before and after the ManipulationInertiaStarting event. The 
ManipulationDeltaEventArgs.Isinertial property reports whether the ManipulationDelta event occurs 
during inertia, so you can check that property and perform different actions, depending on its value. 

6. The ManipulationCompleted event occurs when the manipulation and any inertia ends. That is, after all 
the ManipulationDelta events occur, the ManipulationCompleted event occurs to signal that the 
manipulation is complete. 


The UlElement also defines the ManipulationBoundaryFeedback event. This event occurs when the 
ReportBoundaryFeedback method is called in the ManipulationDelta event. The ManipulationBoundaryFeedback 
event enables applications or components to provide visual feedback when an object hits a boundary. For 
example, the Window class handles the ManipulationBoundaryFeedback event to cause the window to slightly 
move when its edge is encountered. 

You can cancel the manipulation by calling the Cancel method on the event arguments in any manipulation 
event except ManipulationBoundaryFeedback event. When you call Cancel, the manipulation events are no 
longer raised and mouse events occur for touch. The following table describes the relationship between the time 
the manipulation is canceled and the mouse events that occur. 














THE EVENT THAT CANCEL IS CALLED IN 


THE MOUSE EVENTS THAT OCCUR EOR INPUT THAT 
ALREADY OCCURRED 


Manipulationstarting and ManipulationStarted 


Mouse down events. 


ManipulationDelta 


Mouse down and mouse move events. 


ManipulationInertiaStarting and ManipulationCompleted Mouse down, mouse move, and mouse up events. 


Note that if you call Cancel when the manipulation is in inertia, the method returns false and the input does 
not raise mouse events. 


The Relationship Between Touch and Manipulation Events 

A UlElement can always receive touch events. When the IsManipulationEnabled property is set to true , a 
UlElement can receive both touch and manipulation events. If the TouchDown event is not handled (that is, the 
Handled property is false ), the manipulation logic captures the touch to the element and generates the 
manipulation events. If the Handled property is set to true in the TouchDown event, the manipulation logic 
does not generate manipulation events. The following illustration shows the relationship between touch events 
and manipulation events. 
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The following list describes the relationship between the touch and manipulation events that is shown in the 
preceding illustration. 


• When the first touch device generates a TouchDown event on a UlElement, the manipulation logic calls 
the CaptureTouch method, which generates the GotTouchCapture event. 


• When the GotTouchCapture occurs, the manipulation logic calls the Manipulation.AddManipulator 
method, which generates the ManipulationStarting event. 


• When the TouchMove events occur, the manipulation logic generates the ManipulationDelta events that 
occur before the ManipulationInertiaStarting event. 

• When the last touch device on the element raises the TouchUp event, the manipulation logic generates 
the ManipulationInertiaStarting event. 


Focus 

There are two main concepts that pertain to focus in WPF: keyboard focus and logical focus. 


Keyboard Focus 





































Keyboard focus refers to the element that is receiving keyboard input. There can be only one element on the 
whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have 
IsKeyboardFocused set to true . The static Keyboard method FocusedElement returns the element that currently 
has keyboard focus. 

Keyboard focus can be obtained by tabbing to an element or by clicking the mouse on certain elements, such as 
a TextBox. Keyboard focus can also be obtained programmatically by using the Focus method on the Keyboard 
class. Focus attempts to give the specified element keyboard focus. The element returned by Focus is the 
element that currently has keyboard focus. 

In order for an element to obtain keyboard focus the Focusable property and the IsVisible properties must be 
set to true. Some classes, such as Panel, have Focusable set to false by default; therefore, you may have to set 
this property to true if you want that element to be able to obtain focus. 

The following example uses Focus to set keyboard focus on a Button. The recommended place to set initial focus 
in an application is in the Loaded event handler. 

private void OnLoaded(object sender, RoutedEventArgs e) 

{ 

// Sets keyboard focus on tbe first Button in tbe sample. 

Keyboard.Focus(firstButton); 

} 

Private Sub OnLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs) 

' Sets keyboard focus on the first Button in the sample. 

Keyboard.Focus(firstButton) 

End Sub 

For more information about keyboard focus, see Focus Overview. 

Logical Focus 

Logical focus refers to the FocusManager.FocusedElement in a focus scope. There can be multiple elements that 
have logical focus in an application, but there may only be one element that has logical focus in a particular 
focus scope. 

A focus scope is a container element that keeps track of the FocusedElement within its scope. When focus leaves 
a focus scope, the focused element will lose keyboard focus but will retain logical focus. When focus returns to 
the focus scope, the focused element will obtain keyboard focus. This allows for keyboard focus to be changed 
between multiple focus scopes but insures that the focused element within the focus scope remains the focused 
element when focus returns. 

An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the 
FocusManager attached property IsFocusScope to true , or in code by setting the attached property by using 
the SetIsFocusScope method. 

The following example makes a StackPanel into a focus scope by setting the IsFocusScope attached property. 

<StackPanel Mame="focusScopel" 

FocusManager.IsFocusScope="True" 

Height="200" Wldth="200"> 

<Button Name="buttonl" Height="50" Widtb="50"/> 

<Button Name="button2" Height="50" Widtb="50"/> 

</StackPanel> 






StackPanel focuseScope2 = new StackPanel(); 
FocusManager.SetIsFocusScope(focuseScope2j true); 


Dim focuseScope2 As New StackPanel() 

FocusManager.SetIsFocusScope(focuseScope2j True) 

Classes in WPF which are focus scopes by default are Window, Menu, Tool Bar, and ContextMenu. 

An element that has keyboard focus will also have logical focus for the focus scope it belongs to; therefore, 
setting focus on an element with the Focus method on the Keyboard class or the base element classes will 
attempt to give the element keyboard focus and logical focus. 

To determine the focused element in a focus scope, use GetFocusedElement. To change the focused element for 
a focus scope, use SetFocusedElement. 

For more information about logical focus, see Focus Overview. 

Mouse Position 

The WPF input API provides helpful information with regard to coordinate spaces. For example, coordinate 
( 0 , 0 ) is the upper-left coordinate, but the upper-left of which element in the tree? The element that is the input 
target? The element you attached your event handler to? Or something else? To avoid confusion, the WPF input 
API requires that you specify your frame of reference when you work with coordinates obtained through the 
mouse. The GetPosition method returns the coordinate of the mouse pointer relative to the specified element. 

Mouse Capture 

Mouse devices specifically hold a modal characteristic known as mouse capture. Mouse capture is used to 
maintain a transitional input state when a drag-and-drop operation is started, so that other operations involving 
the nominal on-screen position of the mouse pointer do not necessarily occur. During the drag, the user cannot 
click without aborting the drag-and-drop, which makes most mouseover cues inappropriate while the mouse 
capture is held by the drag origin. The input system exposes APIs that can determine mouse capture state, as 
well as APIs that can force mouse capture to a specific element, or clear mouse capture state. For more 
information on drag-and-drop operations, see Drag and Drop Overview. 

Commands 

Commands enable input handling at a more semantic level than device input. Commands are simple directives, 
such as Cut, Copy, Paste , or Open . Commands are useful for Centralizing your Command logic. The Same 
command might be accessed from a Menu, on a ToolBar, or through a keyboard shortcut. Commands also 
provide a mechanism for disabling controls when the command becomes unavailable. 

RoutedCommand is the WPF implementation of ICommand. When a RoutedCommand is executed, a 
PreviewExecuted and an Executed event are raised on the command target, which tunnel and bubble through 
the element tree like other input. If a command target is not set, the element with keyboard focus will be the 
command target. The logic that performs the command is attached to a CommandBinding. When an Executed 
event reaches a CommandBinding for that specific command, the ExecutedRoutedEventHandler on the 
CommandBinding is called. This handler performs the action of the command. 

For more information on commanding, see Commanding Overview. 

WPF provides a library of common commands which consists of ApplicationCommands, MediaCommands, 
ComponentCommands, NavigationCommands, and EditingCommands, or you can define your own. 






The following example shows how to set up a Menultem so that when it is clicked it will invoke the Paste 
command on the TextBox, assuming the TextBox has keyboard focus. 


<StackPanel> 

<Menu> 

<MenuItem Command="ApplicationCommands.Paste" /> 
</Menu> 

<TextBox /> 

</StackPanel> 


// Creating the UI objects 

StackPanel mainStackPanel = new StackPanel(); 
TextBox pasteTextBox = new TextBox(); 

Menu stackPanelMenu = new Henu(); 

Menultem pasteMenuItem = new Menultem(); 

// Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem); 
mainStackPanel.Children.Add(stackPanelMenu); 
mainStackPanel.Children.Add(pasteTextBox); 

// Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste; 

// Setting the command target to the TextBox 
pasteMenuItem.CommandTarget = pasteTextBox; 


' Creating the UI objects 

Dim mainStackPanel As New StackPanel() 

Dim pasteTextBox As New TextBox() 

Dim StackPanelMenu As New Menu() 

Dim pasteMenuItem As New Menultem() 

' Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem) 
mainStackPanel.Children.Add(stackPanelMenu) 
mainStackPanel.Children.Add(pasteTextBox) 

' Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste 


For more information about commands in WPF, see Commanding Overview. 

The Input System and Base Elements 

Input events such as the attached events defined by the Mouse, Keyboard, and Stylus classes are raised by the 
input system and injected into a particular position in the object model based on hit testing the visual tree at run 
time. 

Each of the events that Mouse, Keyboard, and Stylus define as an attached event is also re-exposed by the base 
element classes UlElement and ContentElement as a new routed event. The base element routed events are 
generated by classes handling the original attached event and reusing the event data. 

When the input event becomes associated with a particular source element through its base element input 
event implementation, it can be routed through the remainder of an event route that is based on a combination 
of logical and visual tree objects, and be handled by application code. Generally, it is more convenient to handle 
these device-related input events using the routed events on UlElement and ContentElement, because you can 
use more intuitive event handler syntax both in XAML and in code. You could choose to handle the attached 
event that initiated the process instead, but you would face several issues: the attached event may be marked 



handled by the base element class handling, and you need to use accessor methods rather than true event 
syntax in order to attach handlers for attached events. 

What's Next 

You now have several techniques to handle input in WPF. You should also have an improved understanding of 
the various types of input events and the routed event mechanisms used by WPF. 

Additional resources are available that explain WPF framework elements and event routing in more detail. See 
the following overviews for more information, Commanding Overview, Focus Overview, Base Elements 
Overview, Trees in WPF, and Routed Events Overview. 

See also 

• Focus Overview 

• Commanding Overview 

• Routed Events Overview 

• Base Elements Overview 

• Properties 
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Commanding is an input mechanism in Windows Presentation Foundation (WPF) which provides input 
handling at a more semantic level than device input. Examples of commands are the Copy, Cut, and Paste 
operations found on many applications. 

This overview defines what commands are in WPF, which classes are part of the commanding model, and how 
to use and create commands in your applications. 

This topic contains the following sections: 

• What Are Commands? 

• Simple Command Example in WPF 

• Four Main Concepts in WPF Commanding 

• Command Library 

• Creating Custom Commands 

What Are Commands? 

Commands have several purposes. The first purpose is to separate the semantics and the object that invokes a 
command from the logic that executes the command. This allows for multiple and disparate sources to invoke 
the same command logic, and it allows the command logic to be customized for different targets. For example, 
the editing operations Copy, Cut, and Paste, which are found in many applications, can be invoked by using 
different user actions if they are implemented by using commands. An application might allow a user to cut 
selected objects or text by either clicking a button, choosing an item in a menu, or using a key combination, such 
as CTRL+X. By using commands, you can bind each type of user action to the same logic. 

Another purpose of commands is to indicate whether an action is available. To continue the example of cutting 
an object or text, the action only makes sense when something is selected. If a user tries to cut an object or text 
without having anything selected, nothing would happen. To indicate this to the user, many applications disable 
buttons and menu items so that the user knows whether it is possible to perform an action. A command can 
indicate whether an action is possible by implementing the CanExecute method. A button can subscribe to the 
CanExecuteChanged event and be disabled if CanExecute returns false or be enabled if CanExecute returns 
true . 

The semantics of a command can be consistent across applications and classes, but the logic of the action is 
specific to the particular object acted upon. The key combination CTRL+X invokes the Cut command in text 
classes, image classes, and Web browsers, but the actual logic for performing the Cut operation is defined by 
the application that performs the cut. A RoutedCommand enables clients to implement the logic. A text object 
may cut the selected text into the clipboard, while an image object may cut the selected image. When an 
application handles the Executed event, it has access to the target of the command and can take appropriate 
action depending on the target's type. 

Simple Command Example in WPF 

The simplest way to use a command in WPF is to use a predefined RoutedCommand from one of the command 
library classes; use a control that has native support for handling the command; and use a control that has 
native support for invoking a command. The Paste command is one of the predefined commands in the 






ApplicationCommands class. The TextBox control has built in logic for handling the Paste command. And the 
Menultem class has native support for invoking commands. 

The following example shows how to set up a Menultem so that when it is clicked it will invoke the Paste 
command on a TextBox, assuming the TextBox has keyboard focus. 

<StackPanel> 

<Menu> 

<MenuItem Command="ApplicationCommands.Paste" /> 

</Henu> 

<TextBox /> 

</StackPanel> 


// Creating the UI objects 

StackPanel mainStackPanel = new StackPanel(); 
TextBox pasteTextBox = new TextBox(); 

Menu stackPanelMenu = new Menu(); 

Menultem pasteMenuItem = new Menultem(); 

// Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem); 
mainStackPanel.Children.Add(stackPanelMenu); 
mainStackPanel.Children.Add(pasteTextBox); 

// Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste; 

// Setting the command target to the TextBox 
pasteMenuItem.CommandTarget = pasteTextBox; 


' Creating the UI objects 

Dim mainStackPanel As New StackPanel() 

Dim pasteTextBox As New TextBox() 

Dim StackPanelMenu As New Menu() 

Dim pasteMenuItem As New Menultem() 

' Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem) 
mainStackPanel.Children.Add(stackPanelMenu) 
mainStackPanel.Children.Add(pasteTextBox) 

' Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste 


Four Main Concepts in WPF Commanding 

The routed command model in WPF can be broken up into four main concepts: the command, the command 
source, the command target, and the command binding: 

• The commands the action to be executed. 

• The command source \s the object which invokes the command. 

• The command target\s the object that the command is being executed on. 

• The command binding\s the ob\ect'Nh\ch maps the command logic to the command. 

In the previous example, the Paste command is the command, the Menultem is the command source, the 
TextBox is the command target, and the command binding is supplied by the TextBox control. It is worth noting 
that it is not always the case that the CommandBinding is supplied by the control that is the command target 



class. Quite often the CommandBinding must be created by the application developer, or the CommandBinding 
might be attached to an ancestor of the command target. 

Commands 

Commands in WPF are created by implementing the ICommand interface. ICommand exposes two methods, 
Execute, and CanExecute, and an event, CanExecuteChanged. Execute performs the actions that are associated 
with the command. CanExecute determines whether the command can execute on the current command target. 
CanExecuteChanged is raised if the command manager that centralizes the commanding operations detects a 
change in the command source that might invalidate a command that has been raised but not yet executed by 
the command binding. The WPF implementation of ICommand is the RoutedCommand class and is the focus of 
this overview. 

The main sources of input in WPF are the mouse, the keyboard, ink, and routed commands. The more device- 
oriented inputs use a RoutedEvent to notify objects in an application page that an input event has occurred. A 
RoutedCommand is no different. The Execute and CanExecute methods of a RoutedCommand do not contain 
the application logic for the command, but rather they raise routed events that tunnel and bubble through the 
element tree until they encounter an object with a CommandBinding. The CommandBinding contains the 
handlers for these events and it is the handlers that perform the command. For more information on event 
routing in WPF, see Routed Events Overview. 

The Execute method on a RoutedCommand raises the PreviewExecuted and the Executed events on the 
command target. The CanExecute method on a RoutedCommand raises the CanExecute and PreviewCanExecute 
events on the command target. These events tunnel and bubble through the element tree until they encounter 
an object which has a CommandBinding for that particular command. 

WPF supplies a set of common routed commands spread across several classes: MediaCommands, 
ApplicationCommands, NavigationCommands, ComponentCommands, and EditingCommands. These classes 
consist only of the RoutedCommand objects and not the implementation logic of the command. The 
implementation logic is the responsibility of the object on which the command is being executed on. 

Command Sources 

A command source is the object which invokes the command. Examples of command sources are Menultem, 
Button, and KeyGesture. 

Command sources in WPF generally implement the ICommandSource interface. 

ICommandSource exposes three properties: Command, CommandTarget, and CommandParameter: 

• Command is the command to execute when the command source is invoked. 

• CommandTarget is the object on which to execute the command. It is worth noting that in WPF the 
CommandTarget property on ICommandSource is only applicable when the ICommand is a 
RoutedCommand. If the CommandTarget is set on an ICommandSource and the corresponding 
command is not a RoutedCommand, the command target is ignored. If the CommandTarget is not set, 
the element with keyboard focus will be the command target. 

• CommandParameter is a user-defined data type used to pass information to the handlers implementing 
the command. 

The WPF classes that implement ICommandSource are ButtonBase, Menultem, Hyperlink, and InputBinding. 
ButtonBase, Menultem, and Hyperlink invoke a command when they are clicked, and an InputBinding invokes a 
command when the InputGesture associated with it is performed. 

The following example shows how to use a Menultem in a ContextMenu as a command source for the 
Properties command. 


<StackPanel> 

<StackPanel.ContextMenu> 

<ContextMenu> 

<MenuItem Command="ApplicationCommands.Properties" /> 
</ContextMenu> 

</StackPanel.ContextMenu> 

</StackPanel> 


StackPanel cmdSourcePanel = new StackPanel(); 

ContextMenu cmdSourceContextMenu = new ContextMenu(); 
Henultem cmdSourceMenuItem = new Menultem(); 

// Add ContextMenu to the StackPanel. 
cmdSourcePanel.ContextMenu = cmdSourceContextMenuj 
cmdSourcePanel.ContextMenu.Items.Add(cmdSourceMenuItem); 

// Associate Command with Menultem. 

cmdSourceMenuItem.Command = ApplicationCommands.Properties; 


Dim cmdSourcePanel As Mew StackPanel() 

Dim cmdSourceContextMenu As New ContextMenu() 

Dim cmdSourceMenuItem As New Menultem() 

' Add ContextMenu to the StackPanel. 
cmdSourcePanel.ContextMenu = cmdSourceContextMenu 
cmdSourcePanel.ContextMenu.Items.Add(cmdSourceMenuItem) 

' Associate Command with Menultem. 

cmdSourceMenuItem.Command = ApplicationCommands.Properties 


Typically, a command source will listen to the CanExecuteChanged event. This event informs the command 
source that the ability of the command to execute on the current command target may have changed. The 
command source can query the current status of the RoutedCommand by using the CanExecute method. The 
command source can then disable itself if the command cannot execute. An example of this is a Menultem 
graying itself out when a command cannot execute. 

An InputGesture can be used as a command source. Two types of input gestures in WPF are the KeyGesture and 
MouseGesture. You can think of a KeyGesture as a keyboard shortcut, such as CTRL+C. A KeyGesture is 
comprised of a Key and a set of ModifierKeys. A MouseGesture is comprised of a MouseAction and an optional 
set of ModifierKeys. 

In order for an InputGesture to act as a command source, it must be associated with a command. There are a 
few ways to accomplish this. One way is to use an InputBinding. 

The following example shows how to create a KeyBinding between a KeyGesture and a RoutedCommand. 

<Window.InputBindings> 

<KeyBinding Key="B" 

Modifiers="Control" 

Command="ApplicationCommands.Open" /> 

</Window.InputBindingsx 




KeyGesture OpenKeyGesture = new KeyGesture( 

Key.B, 

ModifierKeys.Control); 

KeyBinding OpenCtndKeybinding = new KeyBinding( 
ApplicationCommands.Openj 
OpenKeyGesture); 

this. InputBindings .Add (OpenCtndKeybinding); 


Dim OpenKeyGesture As New KeyGesture(Key.Bj ModifierKeys.Control) 

Dim OpenCmdKeybinding As New KeyBinding(ApplicationCommands.Open, OpenKeyGesture) 
Me.InputBindings.Add(OpenCmdKeybinding) 


Another way to associate an InputGesture to a RoutedCommand is to add the InputGesture to the 
InputGestureCollection on the RoutedCommand. 

The following example shows how to add a KeyGesture to the InputGestureCollection of a RoutedCommand. 

KeyGesture OpenCmdKeyGesture = new KeyGesture( 

Key.B, 

ModifierKeys.Control); 

ApplicationCommands.Open.InputGestures.Add(OpenCmdKeyGesture); 

Dim OpenCmdKeyGesture As New KeyGesture(Key.Bj ModifierKeys.Control) 

ApplicationCommands.Open.InputGestures.Add(OpenCmdKeyGesture) 


Command Binding 

A CommandBinding associates a command with the event handlers that implement the command. 

The CommandBinding class contains a Command property, and PreviewExecuted, Executed, PreviewCanExecute, 
and CanExecute events. 

Command is the command that the CommandBinding is being associated with. The event handlers which are 
attached to the PreviewExecuted and Executed events implement the command logic. The event handlers 
attached to the PreviewCanExecute and CanExecute events determine if the command can execute on the 
current command target. 

The following example shows how to create a CommandBinding on the root Window of an application. The 
CommandBinding associates the Open command with Executed and CanExecute handlers. 

<Window.CommandBindings> 

<CommandBinding Command="ApplicationCommands.Open" 

Executed="OpenCmdExecuted" 

CanExecute="OpenCmdCanExecute"/> 

</Window.CommandBindings> 





// Creating CommandBinding and attaching an Executed and CanExecute handler 
CommandBinding OpenCtndBinding = new CommandBinding( 
ApplicationCommands.Openj 
OpenCmdExecuted^ 

OpenCmdCanExecute); 

this .CommandBindings.Add(OpenCmdBinding); 


' Creating CommandBinding and attaching an Executed and CanExecute handler 

Dim OpenCmdBinding As New CommandBinding(ApplicationCommands.Openj AddressOf OpenCmdExecuted^ AddressOf 
OpenCmdCanExecute) 

Me.CommandBindings.Add(OpenCmdBinding) 


Next, the ExecutedRoutedEventHandler and a CanExecuteRoutedEventHandler are created. The 
ExecutedRoutedEventHandler opens a MessageBox that displays a string saying the command has been 
executed. The CanExecuteRoutedEventHandler sets the CanExecute property to true . 

void OpenCmdExecuted(object target^ ExecutedRoutedEventArgs e) 

{ 

String commands targetobj; 

command = ((RoutedCommand)e.Command).Name; 

targetobj = ((FrameworkElement)target).Name; 

MessageBox.Show("The " + command + " command has been invoked on target object " + targetobj); 

} 


Private Sub OpenCmdExecuted(ByVal sender As Object, ByVal e As ExecutedRoutedEventArgs) 

Dim command, targetobj As String 

command = CType(e.Command, RoutedCommand).Name 

targetobj = CType(sender, FrameworkElement).Name 

MessageBox.Show("The " + command + " command has been invoked on target object " + targetobj) 
End Sub 


void OpenCmdCanExecute(object sender, CanExecuteRoutedEventArgs e) 

{ 

e.CanExecute = true; 

} 


Private Sub OpenCmdCanExecute(ByVal sender As Object, ByVal e As CanExecuteRoutedEventArgs) 
e.CanExecute = True 
End Sub 


A CommandBinding is attached to a specific object, such as the root Window of the application or a control. The 
object that the CommandBinding is attached to defines the scope of the binding. For example, a 
CommandBinding attached to an ancestor of the command target can be reached by the Executed event, but a 
CommandBinding attached to a descendant of the command target cannot be reached. This is a direct 
consequence of the way a RoutedEvent tunnels and bubbles from the object that raises the event. 

In some situations the CommandBinding is attached to the command target itself, such as with the TextBox class 
and the Cut, Copy, and Paste commands. Quite often though, it is more convenient to attach the 
CommandBinding to an ancestor of the command target, such as the main Window or the Application object, 
especially if the same CommandBinding can be used for multiple command targets. These are design decisions 
you will want to consider when you are creating your commanding infrastructure. 



Command Target 

The command target is the element on which the command is executed. With regards to a RoutedCommand, 
the command target is the element at which routing of the Executed and CanExecute starts. As noted previously, 
in WPF the CommandTarget property on ICommandSource is only applicable when the ICommand is a 
RoutedCommand. If the CommandTarget is set on an ICommandSource and the corresponding command is not 
a RoutedCommand, the command target is ignored. 

The command source can explicitly set the command target. If the command target is not defined, the element 
with keyboard focus will be used as the command target. One of the benefits of using the element with 
keyboard focus as the command target is that it allows the application developer to use the same command 
source to invoke a command on multiple targets without having to keep track of the command target. For 
example, if a Menultem invokes the Paste command in an application that has a TextBox control and a 
PasswordBox control, the target can be either the TextBox or PasswordBox depending on which control has 
keyboard focus. 

The following example shows how to explicitly set the command target in markup and in code behind. 

<StackPanel> 

<Menu> 

<MenuItem Command="ApplicationCommands.Paste" 

CommandTarget="{Binding ElementName=mainTextBox}" /> 

</Henu> 

<TextBox Name="mainTextBox"/> 

</Stacl<Panel> 


// Creating the UI objects 

StackPanel mainStackPanel = new StackPanel(); 
TextBox pasteTextBox = new TextBox(); 

Menu stackPanelMenu = new Menu(); 

Menultem pasteMenuItem = new Menultem(); 

// Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem); 
mainStackPanel.Children.Add(stackPanelMenu); 
mainStackPanel.Children.Add(pasteTextBox); 

// Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste; 

// Setting the command target to the TextBox 
pasteMenuItem.CommandTarget = pasteTextBox; 


' Creating the UI objects 

Dim mainStackPanel As Mew StackPanel() 

Dim pasteTextBox As New TextBox() 

Dim StackPanelMenu As New Menu() 

Dim pasteMenuItem As New Menultem() 

' Adding objects to the panel and the menu 
StackPanelMenu.Items.Add(pasteMenuItem) 
mainStackPanel.Children.Add(stackPanelMenu) 
mainStackPanel.Children.Add(pasteTextBox) 

' Setting the command to the Paste command 
pasteMenuItem.Command = ApplicationCommands.Paste 


The CommandManager 

The CommandManager serves a number of command related functions. It provides a set of static methods for 



adding and removing PreviewExecuted, Executed, PreviewCanExecute, and CanExecute event handlers to and 
from a specific element. It provides a means to register CommandBinding and InputBinding objects onto a 
specific class. The CommandManager also provides a means, through the RequerySuggested event, to notify a 
command when it should raise the CanExecuteChanged event. 

The InvalidateRequerySuggested method forces the CommandManager to raise the RequerySuggested event. 
This is useful for conditions that should disable/enable a command but are not conditions that the 
CommandManager is aware of. 

Command Library 

WPF provides a set of predefined commands. The command library consists of the following classes: 
ApplicationCommands, NavigationCommands, MediaCommands, EditingCommands, and the 
ComponentCommands. These classes provide commands such as Cut, BrowseBack and BrowseForward, Play, 
Stop, and Pause. 

Many of these commands include a set of default input bindings. For example, if you specify that your 
application handles the copy command, you automatically get the keyboard binding "CTRL+C" You also get 
bindings for other input devices, such as Tablet PC pen gestures and speech information. 

When you reference commands in the various command libraries using XAML, you can usually omit the class 
name of the library class that exposes the static command property. Generally, the command names are 
unambiguous as strings, and the owning types exist to provide a logical grouping of commands but are not 
necessary for disambiguation. For instance, you can specify command="Cut" rather than the more verbose 
command="AppiicationCommands.cut" . This is a convenience mechanism that is built in to the WPF XAML 
processor for commands (more precisely, it is a type converter behavior of ICommand, which the WPF XAML 
processor references at load time). 

Creating Custom Commands 

If the commands in the command library classes do not meet your needs, then you can create your own 
commands. There are two ways to create a custom command. The first is to start from the ground up and 
implement the ICommand interface. The other way, and the more common approach, is to create a 
RoutedCommand or a RoutedUICommand. 

For an example of creating a custom RoutedCommand, see Create a Custom RoutedCommand Sample. 

See also 

• RoutedCommand 

• CommandBinding 

• InputBinding 

• CommandManager 

• Input Overview 

• Routed Events Overview 

• Implement ICommandSource 

• How to: Add a Command to a Menultem 

• Create a Custom RoutedCommand Sample 
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In WPF there are two main concepts that pertain to focus: keyboard focus and logical focus. Keyboard focus refers 
to the element that receives keyboard input and logical focus refers to the element in a focus scope that has focus. 
These concepts are discussed in detail in this overview. Understanding the difference in these concepts is 
important for creating complex applications that have multiple regions where focus can be obtained. 

The major classes that participate in focus management are the Keyboard class, the FocusManager class, and the 
base element classes, such as UlElement and ContentElement. For more information about the base elements, see 
the Base Elements Overview. 

The Keyboard class is concerned primarily with keyboard focus and the FocusManager is concerned primarily 
with logical focus, but this is not an absolute distinction. An element that has keyboard focus will also have logical 
focus, but an element that has logical focus does not necessarily have keyboard focus. This is apparent when you 
use the Keyboard class to set the element that has keyboard focus, for it also sets logical focus on the element. 

Keyboard Focus 

Keyboard focus refers to the element that is currently receiving keyboard input. There can be only one element on 
the whole desktop that has keyboard focus. In WPF, the element that has keyboard focus will have 
IsKeyboardFocused set to true . The static property FocusedElement on the Keyboard class gets the element that 
currently has keyboard focus. 

In order for an element to obtain keyboard focus, the Focusable and the IsVisible properties on the base elements 
must be set to true . Some classes, such as the Panel base class, have Focusable set to false by default; 
therefore, you must set Focusable to true if you want such an element to be able to obtain keyboard focus. 

Keyboard focus can be obtained through user interaction with the Ul, such as tabbing to an element or clicking 
the mouse on certain elements. Keyboard focus can also be obtained programmatically by using the Focus 
method on the Keyboard class. The Focus method attempts to give the specified element keyboard focus. The 
returned element is the element that has keyboard focus, which might be a different element than requested if 
either the old or new focus object block the request. 

The following example uses the Focus method to set keyboard focus on a Button. 

private void OnLoaded(object sender^ RoutedEventArgs e) 

{ 

// Sets keyboard focus on the first Button in the sample. 

Keyboard.Focus(firstButton); 

} 

Private Sub OnLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs) 

' Sets keyboard focus on the first Button in the sample. 

Keyboard.Focus(firstButton) 

End Sub 

The IsKeyboardFocused property on the base element classes gets a value indicating whether the element has 
keyboard focus. The IsKeyboardFocusWithin property on the base element classes gets a value indicating whether 
the element or any one of its visual child elements has keyboard focus. 

When setting initial focus at application startup, the element to receive focus must be in the visual tree of the 









initial window loaded by the application, and the element must have Focusable and IsVisible set to true . The 
recommended place to set initial focus is in the Loaded event handler. A Dispatcher callback can also be used by 
calling Invoke or Begininvoke. 

Logical Focus 

Logical focus refers to the FocusManager.FocusedElement in a focus scope. A focus scope is an element that keeps 
track of the FocusedElement within its scope. When keyboard focus leaves a focus scope, the focused element will 
lose keyboard focus but will retain logical focus. When keyboard focus returns to the focus scope, the focused 
element will obtain keyboard focus. This allows for keyboard focus to be changed between multiple focus scopes 
but ensures that the focused element in the focus scope regains keyboard focus when focus returns to the focus 
scope. 

There can be multiple elements that have logical focus in an application, but there may only be one element that 
has logical focus in a particular focus scope. 

An element that has keyboard focus has logical focus for the focus scope it belongs to. 

An element can be turned into a focus scope in Extensible Application Markup Language (XAML) by setting the 
FocusManager attached property IsFocusScope to true . In code, an element can be turned into a focus scope by 
calling SetIsFocusScope. 

The following example makes a StackPanel into a focus scope by setting the IsFocusScope attached property. 

<StackPanel Name="focusScopel" 

FocusManager.IsFocusScope="True" 

Height="200" Width="200"> 

<Button Name="buttonl" Helght="50" Width="50"/> 

<Button Name="button2" Height="50" Width="50"/> 

</StackPanel> 


StackPanel focuseScope2 = new StackPanel()j 
FocusManager.SetIsFocusScope(focuseScope2j true)j 


Dim focuseScope2 As New StackPanel() 
FocusManager.SetIsFocusScope(focuseScope2j True) 


GetFocusScope returns the focus scope for the specified element. 

Classes in WPF which are focus scopes by default are Window, Menultem, ToolBar, and ContextMenu. 

GetFocusedElement gets the focused element for the specified focus scope. SetFocusedElement sets the focused 
element in the specified focus scope. SetFocusedElement is typically used to set the initial focused element. 

The following example sets the focused element on a focus scope and gets the focused element of a focus scope. 

// Sets the focused element in focusScopel 
// focusScopel is a StackPanel. 

FocusManager.SetFocusedElement(focusScopelj button2)j 
// Gets the focused element for focusScope 1 

IlnputElement focusedElement = FocusManager.GetFocusedElement(focusScopel); 






' Sets the focused element in focusScopel 
' focusScopel is a StackPanel. 

FocusManagen.SetFocusedElement(focusScopelj button2) 

' Gets the focused element for focusScope 1 

Dim focusedElement As IlnputElement = FocusManager.GetFocusedElement(focusScopel) 


Keyboard Navigation 

The KeyboardNavigation class is responsible for implementing default keyboard focus navigation when one of 
the navigation keys is pressed. The navigation keys are: TAB, SHIFT+TAB, CTRL+TAB, CTRL+SHIFT+TAB, UPARROW, 
DOWNARROW, LEFTARROW, and RIGHTARROW keys. 

The navigation behavior of a navigation container can be changed by setting the attached KeyboardNavigation 
properties TabNavigation, ControlTabNavigation, and DirectionalNavigation. These properties are of type 
KeyboardNavigationMode and the possible values are Continue, Local, Contained, Cycle, Once, and None. The 
default value is Continue, which means the element is not a navigation container. 

The following example creates a Menu with a number of Menultem objects. The TabNavigation attached property 
is set to Cycle on the Menu. When focus is changed using the tab key within the Menu, focus will move from each 
element and when the last element is reached focus will return to the first element. 


<Menu KeyboardNavigation.TabNavlgation="Cycle"> 
<MenuItem Header'="Menu Item 1" /> 

<MenuItem Header'="Menu Item 2" /> 

<MenuItem Header'="Menu Item 3" /> 

<MenuItem Header'="Menu Item 4" /> 

</Menu> 


Menu navigationMenu = new Menu(); 

Menultem iteml = new Menultem(); 

Menultem item2 = new Menultem(); 

Menultem item3 = new Menultem(); 

Menultem item4 = new Menultem(); 

navigatlonMenu.Items.Add(iteml); 
navigationMenu.Items.Add(item2); 
navigationMenu.Items.Add(item3); 
navigatlonMenu.Items.Add(item4); 

KeyboardNavigation.SetTabMavigation(navigationMenUj 
KeyboardNavigationMode.Cycle); 


Dim navigationMenu As New Menu() 

Dim iteml As New Menultem() 

Dim item2 As New Menultem() 

Dim itemB As New Menultem() 

Dim item4 As New Menultem() 

navigatlonMenu.Items.Add(iteml) 
navigationMenu.Items.Add(item2) 
navigationMenu. Items. Add (it em3) 
navigationMenu.Items.Add(item4) 

KeyboardNavigation.SetTabNavigation(navigationMenUj KeyboardNavigationMode.Cycle) 




Navigating Focus Programmatically 

Additional API to work with focus are MoveFocus and PredictFocus. 

MoveFocus changes focus to the next element in the application. A TraversalRequest is used to specify the 
direction. The FocusNavigationDirection passed to MoveFocus specifies the different directions focus can be 
moved, such as First, Last, Up and Down. 

The following example uses MoveFocus to change the focused element. 

// Creating a FocusNavigationDirection object and setting it to a 
// local field that contains the direction selected. 

FocusNavigationDirection focusDirection = _focusMoveValue; 

// MoveFocus takes a TraveralReqest as its argument. 

TraversalRequest request = new TraversalRequest(focusDirection); 

// Gets the element with keyboard focus. 

UIElement elementWithFocus = Keyboard.FocusedElement as UIElement; 

// Change keyboard focus, 
if (elementWithFocus != null) 

{ 

elementWithFocus.MoveFocus(request); 

} 


' Creating a FocusNavigationDirection object and setting it to a 
' local field that contains the direction selected. 

Dim focusDirection As FocusNavigationDirection = _focusMoveValue 

' MoveFocus takes a TraveralReqest as its argument. 

Dim request As New TraversalRequest(focusDirection) 

' Gets the element with keyboard focus. 

Dim elementWithFocus As UIElement = TryCast(Keyboard.FocusedElement, UIElement) 

' Change keyboard focus. 

If elementWithFocus IsNot Nothing Then 
elementWithFocus.MoveFocus(request) 

End If 


PredictFocus returns the object which would receive focus if focus were to be changed. Currently, only Up, Down, 
Left, and Right are supported by PredictFocus. 


Focus Events 

The events related to keyboard focus are PreviewGotKeyboardFocus, GotKeyboardFocus and 
PreviewLostKeyboardFocus, LostKeyboardFocus. The events are defined as attached events on the Keyboard class, 
but are more readily accessible as equivalent routed events on the base element classes. For more information 
about events, see the Routed Events Overview. 

GotKeyboardFocus is raised when the element obtains keyboard focus. LostKeyboardFocus is raised when the 
element loses keyboard focus. If the PreviewGotKeyboardFocus event or the PreviewLostKeyboardFocusEvent 
event is handled and Handled is set to true , then focus will not change. 

The following example attaches GotKeyboardFocus and LostKeyboardFocus event handlers to a TextBox. 




<Border Border'Brush="Black" Border'Thickness="l" 

Width="200" Height="100" Margin="5"> 

<StackPanel> 

<Label Hor'izontalAlignment="Center'" Content="Type Text In This TextBox" /> 
<TextBox Width="175" 

Height="50" 

Mangin="5" 

TextWrapping="Wrap" 

HorizontalAlignment="Center" 

VerticalScrollBar\/isibility="Auto" 

GotKeyboardFocus="TextBoxGotKeyboardFocus" 

LostKeyboardFocus="TextBoxLostKeyboardFocus" 

KeyDown="SourceTextKeyDown"/> 

</StackPanel> 

</Border> 


When the TextBox obtains keyboard focus, the Background property of the TextBox is changed to LightBlue. 

private void TextBoxGotKeyboardFocus(object sender^ KeyboardFocusChangedEventArgs e) 

{ 

TextBox source = e.Source as TextBox; 

if (source != null) 

{ 

// Change the TextBox color when it obtains focus, 
source.Background = Brushes.LightBlue; 

// Clear the TextBox. 
source.ClearO; 

} 

} 


Private Sub TextBoxGotKeyboardFocus(By\/al sender As Object^ ByVal e As KeyboardFocusChangedEventArgs) 
Dim source As TextBox = TryCast(e.Sourcej TextBox) 

If source IsNot Nothing Then 

' Change the TextBox color when it obtains focus, 
source.Background = Brushes.LightBlue 

' Clear the TextBox. 
source.ClearO 
End If 
End Sub 


When the TextBox loses keyboard focus, the Background property of the TextBox is changed back to white. 

private void TextBoxLostKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e) 

{ 

TextBox source = e.Source as TextBox; 

if (source != null) 

{ 

// Change the TextBox color when it loses focus, 
source.Background = Brushes.White; 

// Set the hit counter back to zero and updates the display, 
this.ResetCounter(); 

} 

} 





Private Sub TextBoxLostKeyboardFocus(ByVal sender As Object, ByVal e As KeyboardFocusChangedEventArgs) 
Dim source As TextBox = TryCast(e.Source, TextBox) 

If source IsNot Nothing Then 

' Change the TextBox color when it loses focus, 
source.Background = Brushes.White 

' Set the hit counter back to zero and updates the display. 

Me.ResetCounterO 
End If 
End Sub 


The events related to logical focus are GotFocus and LostFocus. These events are defined on the FocusManager as 
attached events, but the FocusManager does not expose CLR event wrappers. UlElement and ContentElement 
expose these events more conveniently. 

See also 

• FocusManager 

• UlElement 

• ContentElement 

• Input Overview 

• Base Elements Overview 
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Windows Presentation Foundation (WPF) provides two parallel mechanisms for changing the visual appearance of 
a control when it receives keyboard focus. The first mechanism is to use property setters for properties such as 
IsKeyboardFocused within the style or template that is applied to the control. The second mechanism is to provide 
a separate style as the value of the FocusVisualStyle property; the "focus visual style" creates a separate visual tree 
for an adorner that draws on top of the control, rather than changing the visual tree of the control or other Ul 
element by replacing it. This topic discusses the scenarios where each of these mechanisms is appropriate. 

The Purpose of Focus Visual Style 

The focus visual style feature provides a common "object model" for introducing visual user feedback based on 
keyboard navigation to any Ul element This is possible without applying a new template to the control, or knowing 
the specific template composition. 

However, precisely because the focus visual style feature works without knowing the control templates, the visual 
feedback that can be displayed for a control using a focus visual style is necessarily limited. What the feature 
actually does is to overlay a different visual tree (an adorner) on top of the visual tree as created by a control's 
rendering through its template. You define this separate visual tree using a style that fills the FocusVisualStyle 
property. 

Default Focus Visual Style Behavior 

Focus visual styles act only when the focus action was initiated by the keyboard. Any mouse action or 
programmatic focus change disables the mode for focus visual styles. For more information about the distinctions 
between focus modes, see Focus Overview. 

The themes for controls include a default focus visual style behavior that becomes the focus visual style for all 
controls in the theme. This theme style is identified by the value of the static key FocusVisualStyleKey. When you 
declare your own focus visual style at the application level, you replace this default style behavior from the themes. 
Alternatively, if you define the entire theme, then you should use this same key to define the style for the default 
behavior for your entire theme. 

In the themes, the default focus visual style is generally very simple. The following is a rough approximation: 

<Style x:Key="{x:Static SystemParameters.FocusVisualStyleKey}"> 

<Setter Pr'oper'ty="Control.Template"> 

<Setter.Value> 

<ControlTemplate> 

<Rectangle StrokeThickness="l" 

Stroke="Black" 

StrokeDashArray="l 2" 

SnapsToDevicePixels="true"/> 

</ControlTemplate> 

</Setter.Value> 

</Setter> 

</Style> 


When to Use Focus Visual Styles 


Conceptually, the appearance of focus visual styles applied to controls should be coherent from control to control. 





One way to ensure coherence is to change the focus visual style only if you are composing an entire theme, where 
each control that is defined in the theme gets either the very same focus visual style, or some variation of a style 
that is visually related from control to control. Alternatively, you might use the same style (or similar styles) to style 
every keyboard-focusable element on a page or in a Ul. 

Setting FocusVisualStyle on individual control styles that are not part of a theme is not the intended usage of focus 
visual styles. This is because an inconsistent visual behavior between controls can lead to a confusing user 
experience regarding keyboard focus. If you are intending control-specific behaviors for keyboard focus that are 
deliberately not coherent across a theme, a much better approach is to use triggers in styles for individual input 
state properties, such as IsFocused or IsKeyboardFocused. 

Focus visual styles act exclusively for keyboard focus. As such, focus visual styles are a type of accessibility feature. 
If you want Ul changes for any type of focus, whether via mouse, keyboard, or programmatically, then you should 
not use focus visual styles, and should instead use setters and triggers in styles or templates that are working from 
the value of general focus properties such as IsFocused or IsKeyboardFocusWithin. 

How to Create a Focus Visual Style 

The style you create for a focus visual style should always have the TargetType of Control. The style should consist 
mainly of a ControlTemplate. You do not specify the target type to be the type where the focus visual style is 
assigned to the FocusVisualStyle. 

Because the target type is always Control, you must style by using properties that are common to all controls 
(using properties of the Control class and its base classes). You should create a template that will properly function 
as an overlay to a Ul element and that will not obscure functional areas of the control. Generally, this means that 
the visual feedback should appear outside the control margins, or as temporary or unobtrusive effects that will not 
block the hit testing on the control where the focus visual style is applied. Properties that you can use in template 
binding that are useful for determining sizing and positioning of your overlay template include ActualFleight, 
ActualWidth, Margin, and Padding. 

Alternatives to Using a Focus Visual Style 

For situations where using a focus visual style is not appropriate, either because you are only styling single 
controls or because you want greater control over the control template, there are many other accessible properties 
and techniques that can create visual behavior in response to changes in focus. 

Triggers, setters, and event setters are all discussed in detail in Styling and Templating. Routed event handling is 
discussed in Routed Events Overview. 

IsKeyboard Focused 

If you are specifically interested in keyboard focus, the IsKeyboardFocused dependency property can be used for a 
property Trigger. A property trigger in either a style or template is a more appropriate technique for defining a 
keyboard focus behavior that is very specifically for a single control, and which might not visually match the 
keyboard focus behavior for other controls. 

Another similar dependency property is IsKeyboardFocusWithin, which might be appropriate to use if you want to 
visually call out that keyboard focus is somewhere within compositing or within the functional area of the control. 
For example, you might place an IsKeyboardFocusWithin trigger such that a panel that groups several controls 
appears differently, even though keyboard focus might more precisely be on an individual element within that 
panel. 

You can also use the events GotKeyboardFocus and LostKeyboardFocus (as well as their Preview equivalents). You 
can use these events as the basis for an EventSetter, or you can write handlers for the events in code-behind. 

Other Focus Properties 

If you want all possible causes of changing focus to produce a visual behavior, you should base a setter or trigger 


on the IsFocused dependency property, or alternatively on the GotFocus or LostFocus events used for an 
Events etter. 


See also 

• FocusVisualStyle 

• Styling and Templating 

• Focus Overview 

• Input Overview 
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WPF enables applications to respond to touch. For example, you can interact with an application by using one or 
more fingers on a touch-sensitive device, such as a touchscreen This walkthrough creates an application that 
enables the user to move, resize, or rotate a single object by using touch. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio. 

• A device that accepts touch input, such as a touchscreen, that supports Windows Touch. 

Additionally, you should have a basic understanding of how to create an application in WPF, especially how to 
subscribe to and handle an event. For more information, see Walkthrough: My first WPF desktop application. 

Creating the Application 

To create the application 

1. Create a new WPF Application project in Visual Basic or Visual C# named BasicManipuiation . For more 
information, see Walkthrough: My first WPF desktop application. 

2. Replace the contents of MainWindow.xamI with the following XAML. 

This markup creates a simple application that contains a red Rectangle on a Canvas. The 
IsManipulationEnabled property of the Rectangle is set to true so that it will receive manipulation events. 

The application subscribes to the ManipulationStarting, ManipulationDelta, and ManipulationInertiaStarting 
events. These events contain the logic to move the Rectangle when the user manipulates it. 





<Window x:Class="BasicManipulation.MainWindow" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http: //schemas. microsoft. com/winfx/2006/xaml" 

Title="Movej Size^ and Rotate the Square" 

WindowState="Maximized" 

ManipulationStarting="Window_HanipulationStarting" 

ManipulationDelta="Window_ManipulationDelta" 

ManipulationInertiaStarting="Window_InertiaStarting"> 

<Window.Resources> 

<!--The movement^ rotation, and size of the Rectangle is 
specified by its RenderTransform.--> 
cMatrixTransform x:Key="InitialMatrixTransform"> 
<MatrixTransform.Matrix> 

<Matrix OffsetX="200" OffsetY="200"/> 

</MatrixTransform.Matrix> 

</MatrixTransform> 

</Window.Resources> 

<Canvas> 

<Rectangle Fill="Red" Name="manRect" 

Width="200" Height="200" 

RenderTransform="{StaticResource InitialMatrixTransform}" 
IsManipulationEnabled="true" /> 

</Canvas> 

</Window> 


3. If you are using Visual Basic, in the first line of MainWindow.xamI, replace 
x:Class="BasicManipulation.MainWindow" with x:Class="MainWindow" . 

4. In the HainWindow class, add the following ManipulationStarting event handler. 

The ManipulationStarting event occurs when WPF detects that touch input begins to manipulate an object. 
The code specifies that the position of the manipulation should be relative to the Window by setting the 
ManipulationContainer property. 

void Window_ManipulationStarting(object sender, ManipulationStartingEventArgs e) 

{ 

e.ManipulationContainer = this; 
e.Handled = true; 

} 

Private Sub Window_ManipulationStarting(ByVal sender As Object, ByVal e As 
ManipulationStartingEventArgs) 
e.ManipulationContainer = Me 
e.Handled = True 
End Sub 

5. In the MainWindow class, add the following ManipulationDelta event handler. 

The ManipulationDelta event occurs when the touch input changes position and can occur multiple times 
during a manipulation. The event can also occur after a finger is raised. For example, if the user drags a 
finger across a screen, the ManipulationDelta event occurs multiple times as the finger moves. When the 
user raises a finger from the screen, the ManipulationDelta event keeps occurring to simulate inertia. 

The code applies the DeltaManipulation to the RenderTransform of the Rectangle to move it as the user 
moves the touch input. It also checks whether the Rectangle is outside the bounds of the Window when the 
event occurs during inertia. If so, the application calls the ManipulationDeltaEventArgs.Complete method to 






end the manipulation. 


void Window_ManipulatlonDelta(object sender, ManipulationDeltaEventArgs e) 

{ 

// Get the Rectangle and its RenderTransform matrix. 

Rectangle rectToMove = e.OriginalSource as Rectangle; 

Matrix rectsMatrix = ((MatrixTransform)rectToMove.RenderTransform).Matrix; 
// Rotate the Rectangle. 

rectsMatrix.RotateAt(e.DeltaManipulation.Rotation, 
e.ManipulationOrigin.X, 
e.ManipulationOrigin.Y); 

// Resize the Rectangle. Keep it square 
// so use only the X value of Scale. 
rectsMatrix.ScaleAt(e.DeltaManipulation.Scale.X, 
e.DeltaManipulation.Scale.X, 
e.ManipulationOrigin.X, 
e.ManipulationOrigin.Y); 

// Move the Rectangle. 

rectsMatrix.Translate(e.DeltaManipulation.Translation.X, 
e.DeltaManipulation.Translation.Y); 

// Apply the changes to the Rectangle. 

rectToMove.RenderTransform = new MatrixTransform(rectsMatrix); 

Rect containingRect = 

new Rect(((FrameworkElement)e.ManipulationContainer).RenderSize); 

Rect shapeBounds = 

rectToMove.RenderTransform.TransformBounds( 
new Rect(rectToMove.RenderSize)); 

// Check if the rectangle is completely in the window. 

// If it is not and intertia is occuring, stop the manipulation, 
if (e.lsinertial && !containingRect.Contains(shapeBounds)) 

{ 

e.CompleteO; 

} 

e.Handled = true; 

} 



Private Sub Window_ManipulationDelta(ByVal sender As Object, ByVal e As ManipulationDeltaEventArgs) 

' Get the Rectangle and its RenderTransform matrix. 

Dim rectToMove As Rectangle = e.OriginalSource 

Dim rectTransform As MatrixTransform = rectToMove.RenderTransform 
Dim rectsMatrix As Matrix = rectTransform.Matrix 


' Rotate the shape 

rectsMatrix.RotateAt(e.DeltaManipulation.Rotation, 
e.ManipulationOrigin.X, 
e.ManipulationOrigin.Y) 

' Resize the Rectangle. Keep it square 
' so use only the X value of Scale. 
rectsMatrix.ScaleAt(e.DeltaManipulation.Scale.X, 
e.DeltaManipulation.Scale.X, 
e.ManipulationOrigin.X, 
e.ManipulationOrigin.Y) 

'move the center 

rectsMatrix.Translate(e.DeltaManipulation.Translation.X, 
e.DeltaManipulation.Translation.Y) 

' Apply the changes to the Rectangle. 
rectTransform = New MatrixTransform(rectsMatrix) 
rectToMove.RenderTransform = rectTransform 

Dim container As FrameworkElement = e.ManipulationContainer 
Dim containingRect As New Rect(container.RenderSize) 

Dim shapeBounds As Rect = rectTransform.TransformBounds( 

New Rect(rectToMove.RenderSize)) 

' Check if the rectangle is completely in the window. 

' If it is not and intertia is occuring, stop the manipulation. 

If e.lsinertial AndAlso Not containingRect.Contains(shapeBounds) Then 
e.CompleteO 
End If 

e.Handled = True 
End Sub 

6. In the MainWindow class, add the following ManipulationInertiaStarting event handler. 

The ManipulationInertiaStarting event occurs when the user raises all fingers from the screen. The code sets 
the initial velocity and deceleration for the movement, expansion, and rotation of the rectangle. 




void Window_Iner'tiaStarting(object sender, ManipulationlnertiaStartingEventArgs e) 

{ 

// Decrease the velocity of the Rectangle's movement hy 
// 10 inches per second every second. 

// (10 inches * 96 pixels per inch / 1000ms''2) 

e.TranslationBehavior.DesiredDeceleration = 10.0 * 96.0 / (1000.0 * 1000.0); 

// Decrease the velocity of the Rectangle's resizing hy 
// 0.1 inches per second every second. 

// (0.1 inches * 96 pixels per inch / (1000ms''2) 

e.ExpansionBehavior.DesiredDeceleration = 0.1 * 96 / (1000.0 * 1000.0); 

// Decrease the velocity of the Rectangle's rotation rate hy 
// 2 rotations per second every second. 

// (2 * 360 degrees / (1000ms''2) 

e.RotationBehavior.DesiredDeceleration = 720 / (1000.0 * 1000.0); 
e.Handled = true; 

} 


Private Suh Window_InertiaStarting(ByVal sender As Object, 

ByVal e As ManipulationInertiaStartingEventArgs) 

' Decrease the velocity of the Rectangle's movement by 
' 10 inches per second every second. 

' (10 inches * 96 pixels per inch / 1000ms''2) 

e.TranslationBehavior.DesiredDeceleration = 10.0 * 96.0 / (1000.0 * 1000.0) 

' Decrease the velocity of the Rectangle's resizing by 
' 0.1 inches per second every second. 

' (0.1 inches * 96 pixels per inch / (1000ms''2) 

e.ExpansionBehavior.DesiredDeceleration = 0.1 * 96 / (1000.0 * 1000.0) 

' Decrease the velocity of the Rectangle's rotation rate by 
' 2 rotations per second every second. 

' (2 * 360 degrees / (1000ms''2) 

e.RotationBehavior.DesiredDeceleration = 720 / (1000.0 * 1000.0) 

e.Handled = True 
End Sub 


7. Build and run the project. 

You should see a red square appear in the window. 

Testing the Application 

To test the application, try the following manipulations. Note that you can do more than one of the following at the 
same time. 

• To move the Rectangle, put a finger on the Rectangle and move the finger across the screen. 

• To resize the Rectangle, put two fingers on the Rectangle and move the fingers closer together or farther 
apart from each other. 

• To rotate the Rectangle, put two fingers on the Rectangle and rotate the fingers around each other. 

To cause inertia, quickly raise your fingers from the screen as you perform the previous manipulations. The 
Rectangle will continue to move, resize, or rotate for a few seconds before it stops. 



See also 

• UlElement.ManipulationStarting 

• UlElement.ManipulationDelta 

• UlElement.ManipulationlnertiaStarting 


Input and Commands How-to Topics 

3/5/2019 • 2 minutes to read ^ Edit Online 


The topics in this section describe how to use the input and commanding infrastructure in Windows Presentation 
Foundation (WPF). 

In This Section 

Enable a Command 
Change the Cursor Type 

Change the Color of an Element Using Focus Events 

Apply a FocusVisualStyle to a Control 

Detect When the Enter Key is Pressed 

Create a Rollover Effect Using Events 

Make an Object Follow the Mouse Pointer 

Create a RoutedCommand 

Implement ICommandSource 

Flook Up a Command to a Control with No Command Support 
Hook Up a Command to a Control with Command Support 

Reference 

UlElement 

FrameworkElement 

ContentElement 

FrameworkContentElement 

Keyboard 

Mouse 

FocusManager 


Related Sections 




How to: Enable a Command 

4/8/2019 • 2 minutes to read ^ Edit Online 


The following example demonstrates how to use commanding in Windows Presentation Foundation (WPF). The 
example shows how to associate a RoutedCommand to a Button, create a CommandBinding, and create the event 
handlers which implement the RoutedCommand. For more information on commanding, see the Commanding 
Overview. 

Example 

The first section of code creates the user interface (Ul), which consists of a Button and a StackPanel, and creates a 
CommandBinding that associates the command handlers with the RoutedCommand. 

The Command property of the Button is associated with the Close command. 

The CommandBinding is added to the CommandBindingCollection of the root Window. The Executed and 
CanExecute event handlers are attached to this binding and associated with the Close command. 

Without the CommandBinding there is no command logic, only a mechanism to invoke the command. When the 
Button is clicked, the PreviewExecuted RoutedEvent is raised on the command target followed by the Executed 
RoutedEvent. These events traverse the element tree looking for a CommandBinding for that particular command. 
It is worth noting that because RoutedEvent tunnel and bubble through the element tree, care must be taken in 
where the CommandBinding is put. If the CommandBinding is on a sibling of the command target or another node 
that is not on the route of the RoutedEvent, the CommandBinding will not be accessed. 

<Window x:Class="WCSamples.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

Title="CloseCommand" 

Name="RootWindow" 

> 

<Window.CommandBindings> 

<CommandBinding Command="AppllcationCommands.Close" 

Executed="CloseCommandHandler" 

CanExecute="CanExecuteHandler" 

/> 

</Window.CommandBindings> 

<StackPanel Name="MainStackPanel"> 

<Button Command="ApplicationCommands.Close" 

Content="Close File" /> 

</StackPanel> 

</Window> 





// Create ui elements. 

StackPanel CloseCmdStackPanel = new StackPanel(); 

Button CloseCmdButton = new Button(); 

CloseCmdStackPanel.Children.Add(CloseCmdButton); 

// Set Button's properties. 

CloseCmdButton.Content = "Close File"; 

CloseCmdButton.Command = ApplicationCommands.Close; 

// Create the CommandBinding. 

CommandBinding CloseCommandBinding = new CommandBinding( 

ApplicationCommands.Closej CloseCommandHandlerj CanExecuteHandler); 

// Add the CommandBinding to the root Window. 
RootWindow.CommandBindings.Add(CloseCommandBinding); 


' Create ui elements. 

Dim CloseCmdStackPanel As New StackPanel() 

Dim CloseCmdButton As New Button() 

CloseCmdStackPanel.Children.Add(CloseCmdButton) 

' Set Button's properties. 

CloseCmdButton.Content = "Close File" 

CloseCmdButton.Command = ApplicationCommands.Close 

' Create the CommandBinding. 

Dim CloseCommandBinding As New CommandBinding(ApplicationCommands.Close, AddressOf CloseCommandFlandler, 
AddressOf CanExecuteFlandler) 

' Add the CommandBinding to the root Window. 

RootWindow.CommandBindings.Add(CloseCommandBinding) 


The next section of code implennents the Executed and CanExecute event handlers. 

The Executed handler calls a nnethod to close the open file. The CanExecute handler calls a method to determine 
whether a file is open. If a file is open, CanExecute is set to true ; otherwise, it is set to false . 

// Executed event handler. 

private void CloseCommandHandler(object sender, ExecutedRoutedEventArgs e) 

{ 

// Calls a method to close the file and release resources. 

CloseFileO; 

} 

// CanExecute event handler. 

private void CanExecuteHandler(object sender, CanExecuteRoutedEventArgs e) 

{ 

// Call a method to determine if there is a file open. 

// If there is a file open, then set CanExecute to true, 
if (IsFileOpenedO) 

{ 

e.CanExecute = true; 

} 

// if there is not a file open, then set CanExecute to false, 
else 
{ 

e.CanExecute = false; 

} 

} 






' Executed event handler. 

Private Sub CloseCommandHandler(By\/al sender As Object^ ByVal e As ExecutedRoutedEventArgs) 
' Calls a method to close the file and release resources. 

CloseFileO 
End Sub 

' CanExecute event handler. 

Private Sub CanExecuteHandler(By\/al sender As Object^ ByVal e As CanExecuteRoutedEventArgs) 
' Call a method to determine if there is a file open. 

' If there is a file open^ then set CanExecute to true. 

If IsFileOpened() Then 
e.CanExecute = True 

' if there is not a file open^ then set CanExecute to false. 

Else 

e.CanExecute = False 
End If 
End Sub 


See also 

• Commanding Overview 



How to: Change the Cursor Type 
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This example shows how to change the Cursor of the mouse pointer for a specific element and for the application 
This example consists of a Extensible Application Markup Language (XAML) file and a code behind file. 

Example 

The user interface is created, which consists of a ComboBox to select the desired Cursor, a pair of RadioButton 
objects to determine if the cursor change applies to only a single element or applies to the entire application, and 
Border which is the element that the new cursor is applied to. 




<StackPanel> 

<Border Width="300"> 

<StackPanel Or'ientation="Horizontal" 

HorizontalAlignment="Center"> 

<StackPanel Margin="10"> 

<Label HorizontalAlignment="Left">Cursor Type</Label> 

<ComboBox Width="100" 

SelectionChanged="CursorTypeChanged" 

HorizontalAlignment="Left" 

Name="CursorSelector"> 

<ComboBoxItem Content="AppStarting" /> 

<ComboBoxItem Content="ArrowCD" /> 

<ComboBoxItem Content="Arrow" /> 

<ConiboBoxItem Content="Cross" /> 

<ComboBoxItem Content="HandCursor" /> 

<ComboBoxItem Content="Help" /> 

<ComboBoxItem Content="IBeam" /> 

<ComboBoxItem Content="No" /> 

<ComboBoxItem Content="None" /> 

<ComboBoxItem Content="Pen" /> 

<ComboBoxItem Content="ScrollSE" /> 

<ComboBoxItem Content="ScrollWE" /> 

<ComboBoxItem Content="SizeAll" /> 

<ComboBoxItem Content="SizeNESW" /> 

<ComboBoxItem Content="SizeNS" /> 

<ComboBoxItem Content="SizeNWSE" /> 

<ComboBoxItem Content="SizeWE" /> 

<ComboBoxItem Content="UpArrow" /> 

<ComboBoxItem Content="WaitCursor" /> 

<ComboBoxItem Content="Custom" /> 

</ComboBox> 

</StackPanel> 

<!-- The user can select different cursor types using this ComboBox --> 
<StackPanel Margin="10"> 

<Label HorizontalAlignment="Left">Scope of Cursor</Label> 

<StackPanel> 

<RadioButton Name="rbScopeElement" IsChecked="True" 

Checked="CursorScopeSelected">Display Area Only</RadioButton> 
<RadioButton IMame="rbScopeApplication" 

Checked="CursorScopeSelected">Entire Appliation</RadioButton> 

</StackPanel> 

</StackPanel> 

</StackPanel> 

</Border> 

<!-- When the mouse pointer is over this Border --> 

<!-- the selected cursor type is shown --> 

<Border Name="DisplayArea" Height="250" Width="400" 

Margin="20" Background="AliceBlue"> 

<Label HorizontalAlignment="Center"> 

Move Mouse Pointer Over This Area 
</Label> 

</Border> 

</StackPanel> 


The following code behind creates a SelectionChanged event handler which is called when the cursor type is 
changed in the ComboBox. A switch statement filters on the cursor name and sets the Cursor property on the 
Border which is named DisplayArea. 

If the cursor change is set to "Entire Application", the OverrideCursor property is set to the Cursor property of the 
Border control. This forces the cursor to change for the whole application. 

private void CursorTypeChanged(object sender^ SelectionChangedEventArgs e) 

{ 

ComboBox source = e.Source as ComboBox; 



if (source != null) 

{ 

ComboBoxItem selectedCursor = source.Selecteditem as ComboBoxItem; 

// Changing the cursor of the Border control 

// by setting the Cursor property 

switch (selectedCursor.Content.ToString()) 

{ 

case "AppStarting": 

DisplayArea.Cursor = Cursors.AppStarting; 
break; 

case "ArrowCD": 

DisplayArea.Cursor = Cursors.ArrowCD; 
break; 

case "Arrow": 

DisplayArea.Cursor = Cursors.Arrow; 
break; 

case "Cross": 

DisplayArea.Cursor = Cursors.Cross; 
break; 

case "HandCursor": 

DisplayArea.Cursor = Cursors.Hand; 
break; 

case "Help": 

DisplayArea.Cursor = Cursors.Help; 
break; 

case "IBeam": 

DisplayArea.Cursor = Cursors.IBeam; 
break; 
case "No": 

DisplayArea.Cursor = Cursors.No; 
break; 

case "None": 

DisplayArea.Cursor = Cursors.None; 
break; 
case "Pen": 

DisplayArea.Cursor = Cursors.Pen; 
break; 

case "ScrollSE": 

DisplayArea.Cursor = Cursors.ScrollSE; 
break; 

case "ScrollWE": 

DisplayArea.Cursor = Cursors.ScrollWE; 
break; 

case "SizeAll": 

DisplayArea.Cursor = Cursors.SizeAll; 
break; 

case "SizeNESW": 

DisplayArea.Cursor = Cursors.SizeNESW; 
break; 

case "SizeNS": 

DisplayArea.Cursor = Cursors.SizeNS; 
break; 

case "SizeNWSE": 

DisplayArea.Cursor = Cursors.SizeNWSE; 
break; 

case "SizeWE": 

DisplayArea.Cursor = Cursors.SizeWE; 
break; 

case "UpArrow": 

DisplayArea.Cursor = Cursors.UpArrow; 
break; 

case "WaitCursor": 

DisplayArea.Cursor = Cursors.Wait; 
break; 

case "Custom": 

DisplayArea.Cursor = CustomCursor; 
break; 
default: 


} 


break; 


// If the cursor scope is set to the entire application 
// Use OverrideCursor to force the cursor for all elements 
if (cursorScopeElementOnly == false) 


{ 

Mouse.OverrideCursor = DisplayArea.Cursor; 

} 

} 



} 


' When the Radiobox changeSj a new cursor type is set 

Private Sub CursorTypeChanged(By\/al sender As Objectj ByVal e As SelectionChangedEventArgs) 
Dim item As String = CType(e.Sourcej ComboBox).Selecteditem.Content.ToStringO 


Select Case item 

Case "AppStarting" 

DisplayArea.Cursor = Cursors.AppStarting 
Case "ArrowCD" 


DisplayArea.Cursor = Cursors.ArrowCD 
Case "Arrow" 

DisplayArea.Cursor = Cursors.Arrow 
Case "Cross" 

DisplayArea.Cursor = Cursors.Cross 
Case "HandCursor" 

DisplayArea.Cursor = Cursors.Hand 
Case "Help" 

DisplayArea.Cursor = Cursors.Help 
Case "IBeam" 

DisplayArea.Cursor = Cursors.IBeam 
Case "No" 

DisplayArea.Cursor = Cursors.No 
Case "None" 

DisplayArea.Cursor = Cursors.None 
Case "Pen" 

DisplayArea.Cursor = Cursors.Pen 
Case "ScrollSE" 

DisplayArea.Cursor = Cursors.ScrollSE 
Case "ScrollWE" 

DisplayArea.Cursor = Cursors.ScrollWE 
Case "SizeAll" 

DisplayArea.Cursor = Cursors.SizeAll 
Case "SizeNESW" 

DisplayArea.Cursor = Cursors.SizeNESW 
Case "SizeNS" 

DisplayArea.Cursor = Cursors.SizeNS 
Case "SizeNWSE" 

DisplayArea.Cursor = Cursors.SizeNWSE 
Case "SizeWE" 

DisplayArea.Cursor = Cursors.SizeWE 
Case "UpArrow" 

DisplayArea.Cursor = Cursors.UpArrow 
Case "WaitCursor" 

DisplayArea.Cursor = Cursors.Wait 
Case "Custom" 

DisplayArea.Cursor = CustomCursor 
End Select 


' if the cursor scope is set to the entire application 
' use OverrideCursor to force the cursor for all elements 
If (cursorScopeElementOnly = False) Then 

Mouse.OverrideCursor = DisplayArea.Cursor 
End If 


End Sub 


See also 


• Input Overview 



How to: Change the Color of an Element Using Focus 
Events 
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This example shows how to change the color of an element when it gains and loses focus by using the GotFocus 
and LostFocus events. 

This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. 

Example 

The following XAML creates the user interface, which consists of two Button objects, and attaches event handlers 
for the GotFocus and LostFocus events to the Button objects. 

<StackPanel> 

<StackPanel.Resources> 

<Style TargetType="{x:Type Button}"> 

<Setter Property="Height" Value="20"/> 

<Setter Property="Width" Value="250"/> 

<Setter Property="HorizontalAlignment" Value="Left"/> 

</Style> 

</StackPanel.Resources> 

<Button 

GotFocus="OnGotFocusHandler" 

LostFocus="OnLostFocusHandler">Click Or Tab To Give Keyboard Focus</Button> 

<Button 

GotFocus="OnGotFocusHandler" 

LostFocus="OnLostFocusHandler">Click Or Tab To Give Keyborad Focus</Button> 

</StackPanel> 


The following code behind creates the GotFocus and LostFocus event handlers. When the Button gains keyboard 
focus, the Background of the Button is changed to red. When the Button loses keyboard focus, the Background of 
the Button is changed back to white. 





public partial class Windowl : Window 

{ 

public WindowlO 

{ 

InitializeComponent(); 

} 

// Raised when Button gains focus. 

// Changes the color of the Button to Red. 

private void OnGotFocusHandler(object sender^ RoutedEventArgs e) 

{ 

Button tb = e.Source as Button; 
tb.Background = Brushes.Red; 

} 

// Raised when Button losses focus. 

// Changes the color of the Button back to white. 

private void OnLostFocusHandler(object sender, RoutedEventArgs e) 

{ 

Button tb = e.Source as Button; 
tb.Background = Brushes.White; 

} 


Partial Public Class Windowl 
Inherits Window 

Public Sub IMew() 

InitializeComponent() 

End Sub 

'raised when Button gains focus. Changes the color of the Button to red. 

Private Sub OnGotFocusHandler(By\/al sender As Object, ByVal e As RoutedEventArgs) 
Dim tb As Button = CType(e.Source, Button) 
tb.Background = Brushes.Red 
End Sub 

'raised when Button loses focus. Changes the color back to white. 

Private Sub OnLostFocusFlandler(ByVal sender As Object, ByVal e As RoutedEventArgs) 
Dim tb As Button = CType(e.Source, Button) 
tb.Background = Brushes.White 
End Sub 
End Class 


See also 


• Input Overview 



How to; Apply a FocusVisualStyle to a Control 
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This example shows you how to create a focus visual style in resources and apply the style to a control, using the 
FocusVisualStyle property. 

Example 

The following example defines a style that creates additional control compositing that only applies when that 
control is keyboard focused in the user interface (Ul). This is accomplished by defining a style with a 
ControlTemplate, then referencing that style as a resource when setting the FocusVisualStyle property. 

An external rectangle resembling a border is placed outside of the rectangular area. Unless otherwise modified, the 
sizing of the style uses the ActualHeight and ActualWidth of the rectangular control where the focus visual style is 
applied. This example sets negative values for the Margin to make the border appear slightly outside the focused 
control. 


<Page 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml" 

> 

<Page.Resources> 

<Style x:Key="MyFocusVisual"> 

<Setter Pnoperty="Control.Template"> 

<Setter.Value> 

<ContnolTemplate> 

<Rectangle Mangin="-2" Stnol<eThickness="l" Stroke="Red" StrokeDashArray="l 2"/> 
</ControlTemplate> 

</Setten.Value) 

</Setter> 

</Style> 

</Page.Resources) 

<StackPanel Background="Ivory" Orientation="Horizontal") 

<Canvas Width="10"/) 

<Button Width="100" Height="30" FocusVisualStyle="{DynamicResource MyFocusVisual}") 
Focus Here</Button) 

<Canvas Width="100"/) 

<Button Width="100" Height="30" FocusVisualStyle="{DynamicResource MyFocusVisual}") 
Focus Here</Button) 

</StackPanel) 

</Page) 


A FocusVisualStyle is additive to any control template style that comes either from an explicit style or a theme style; 
the primary style for a control can still be created by using a ControlTemplate and setting that style to the Style 
property. 

Focus visual styles should be used consistently across a theme or a Ul, rather than using a different one for each 
focusable element. For details, see Styling for Focus in Controls, and FocusVisualStyle. 

See also 

• FocusVisualStyle 

• Styling and Templating 

• Styling for Focus in Controls, and FocusVisualStyle 





How to: Detect When the Enter Key Pressed 
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This example shows how to detect when the Enter key is pressed on the keyboard. 

This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. 

Example 

When the user presses the Enter key in the TextBox, the input in the text box appears in another area of the user 
interface (Ul). 

The following XAML creates the user interface, which consists of a StackPanel, a TextBlock, and a TextBox. 

<Stacl<Panel> 

<TextBlocI< Width="300" Height="20"> 

Type some text into the TextBox and press the Enter key. 

</TextBlock> 

<TextBox Width="300" Height="30" Name="textBoxl" 

KeyDown="OnKeyDownHandler"/> 

<TextBlock Width="300" Height="100" Name="textBlockl"/> 

</StackPanel> 


The following code behind creates the KeyDown event handler. If the key that is pressed is the Enter key, a message 
is displayed in the TextBlock. 

private void OnKeyDownHandler(object sender, KeyEventArgs e) 

{ 

if (e.Key == Key.Return) 

{ 

textBlockl.Text = "You Entered: " + textBoxl.Text; 

} 

} 


Private Sub OnKeyDownHandler(ByVal sender As Object, ByVal e As KeyEventArgs) 
If (e.Key = Key.Return) Then 

textBlockl.Text = "You Entered: " + textBoxl.Text 
End If 
End Sub 


See also 


• Input Overview 

• Routed Events Overview 






How to: Create a Rollover Effect Using Events 
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This example shows how to change the color of an element as the mouse pointer enters and leaves the area 
occupied by the element. 

This example consists of a Extensible Application Markup Language (XAML) file and a code-behind file. 

NOTE 

This example demonstrates how to use events, but the recommended way to achieve this same effect is to use a Trigger in a 
style. For more information, see Styling and Templating. 


Example 

The following XAML creates the user interface, which consists of Border around a TextBlock, and attaches the 
MouseEnter and MouseLeave event handlers to the Border. 


<StackPanel> 

<Bonder MouseEnten="OnMouseEntenHandler" 
MouseLeave="OnMouseLeaveHandler" 


Name="borderl" Mangin="10" 

BordenThickness="l" 

BordenBnush="Black" 

VenticalAlignment="Center" 

Width="300" Height="100"> 

<Label Margin="10" FontSize="14" 

HorizontalAlignment="Center">Move Cursor Over Me</Label> 

</Border> 

</StackPanel> 


The following code behind creates the MouseEnter and MouseLeave event handlers. When the mouse pointer 
enters the Border, the background of the Border is changed to red. When the mouse pointer leaves the Border, the 
background of the Border is changed back to white. 

public partial class Windowl : Window 

{ 

public WindowlO 

{ 

InitializeComponent(); 

} 

// raised when mouse cursor enters the area occupied by the element 
void OnMouseEnterHandlerfobject sender, MouseEventArgs e) 

{ 

borderl.Background = Brushes.Red; 

} 

// raised when mouse cursor leaves the area occupied by the element 
void OnMouseLeaveHandlerfobject sender, MouseEventArgs e) 

{ 

borderl.Background = Brushes.White; 

} 

} 







Partial Public Class Windowl 
Inherits Window 


Public Sub New() 

InitializeComponent() 

End Sub 

' raised when mouse cursor enters the 
Private Sub OnMouseEnterHandler(ByVal 
borderl.Background = Brushes.Red 
End Sub 

' raised when mouse cursor leaves the 
Private Sub OnMouseLeaveHandler(By\/al 
borderl.Background = Brushes.White 
End Sub 
End Class 


are occupied by the element 
sender As Object^ ByVal e As 


are occupied by the element 
sender As Object^ ByVal e As 


MouseEventArgs) 


MouseEventArgs) 
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This example shows how to change the dimensions of an object when the mouse pointer moves on the screen. 

The example includes an Extensible Application Markup Language (XAML) file that creates the user interface (Ul) 
and a code-behind file that creates the event handler. 

Example 

The following XAML creates the Ul, which consists of an Ellipse inside of a StackPanel, and attaches the event 
handler for the MouseMove event. 


<Window x:Class="WCSamples.Windowl" 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http: //schemas. micnosoft. com/winfx/2006/xaml" 
Title="mouseMoveWithPointer" 

Height="400" 

Width="500" 

> 

<Canvas MouseMove="MouseMoveHandler" 

Backgnound="LemonChiffon"> 

<Ellipse Name="ellipse" Flll="LightBlue" 

Width="100" Height="100"/> 

</Canvas> 

</Window> 


The following code behind creates the MouseMove event handler. When the mouse pointer moves, the height and 
the width of the Ellipse are increased and decreased. 

// raised when the mouse pointer moves. 

// Expands the dimensions of an Ellipse when the mouse moves, 
private void HouseMoveHandler(object sender, MouseEventArgs e) 

{ 

// Get the x and y coordinates of the mouse pointer. 

System.Windows.Point position = e.GetPosition(this); 
double pX = position.X; 
double pY = position.Y; 

// Sets the Height/Width of the circle to the mouse coordinates, 
ellipse.Width = pX; 
ellipse.Height = pY; 

} 






' raised when the mouse pointer moves. 

' Expands the dimensions of an Ellipse when the mouse moves. 

Private Sub OnMouseMoveHandler(ByVal sender As Object, ByVal e As MouseEventArgs) 

'Get the x and y coordinates of the mouse pointer. 

Dim position As System.Windows.Point 
position = e.GetPosition(Me) 

Dim pX As Double 
pX = position.X 
Dim pY As Double 
pY = position.Y 

'Set the Height and Width of the Ellipse to the mouse coordinates, 
ellipsel.Height = pY 
ellipsel.Width = pX 
End Sub 


See also 

• Input Overview 
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This example shows how to create a custom RoutedCommand and how to implement the custom command by 
creating a ExecutedRoutedEventHandler and a CanExecuteRoutedEventHandler and attaching them to a 
CommandBinding. For more information on commanding, see the Commanding Overview. 

Example 

The first step in creating a RoutedCommand is defining the command and instantiating it 

public static RoutedCommand CustomRoutedCommand = new RoutedCommand(); 

Public Shared CustomRoutedCommand As New RoutedCommand() 


In order to use the command in an application, event handlers which define what the command does must be 
created 


private void ExecutedCustomCommand(object sender^ 
ExecutedRoutedEventArgs e) 

{ 

MessageBox.Show("Custom Command Executed"); 

} 


Private Sub ExecutedCustomCommand(ByVal sender As Object^ ByVal e As ExecutedRoutedEventArgs) 
MessageBox.Show("Custom Command Executed") 

End Sub 


// CanExecuteRoutedEventHandler that only returns true if 
// the source is a control. 

private void CanExecuteCustomCommand(object sender^ 
CanExecuteRoutedEventArgs e) 

{ 

Control target = e.Source as Control; 

if(target != null) 

{ 

e.CanExecute = true; 

} 

else 

{ 

e.CanExecute = false; 

} 

} 






' CanExecuteRoutedEventHandler that only returns true if 
' the source is a control. 

Private Sub CanExecuteCustomCommand(ByVal sender As Object^ ByVal e As CanExecuteRoutedEventArgs) 
Dim target As Control = TryCast(e.Sourcej Control) 

If target IsNot Nothing Then 
e.CanExecute = True 

Else 

e.CanExecute = False 
End If 
End Sub 


Next, a CommandBinding is created which associates the command with the event handlers. The CommandBinding 
is created on a specific object. This object defines the scope of the CommandBinding in the element tree 

<Window x:Class="SDKSamples.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
xmlns:custom="clr-namespace:SDKSamples" 

Height="600" Width="800" 

> 

<Window.CommandBindings> 

<CommandBinding Command="{x:Static custom:Windowl.CustomRoutedCommand}" 

Executed="ExecutedCustomCommand" 

CanExecute="CanExecuteCustomCommand" /> 

</Window.CommandBindings> 


CommandBinding customCommandBinding = new CommandBinding( 

CustomRoutedCommandj ExecutedCustomCommandj CanExecuteCustomCommand)j 

// attach CommandBinding to root window 
this.CommandBindings.Add(customCommandBinding)j 


Dim customCommandBinding As New CommandBinding(CustomRoutedCommandj AddressOf ExecutedCustomCommand, AddressOf 
CanExecuteCustomCommand) 

' attach CommandBinding to root window 
Me.CommandBindings.Add(customCommandBinding) 


The final step is invoking the command. One way to invoke a command is to associate it with a ICommandSource, 
such as a Button. 


cStackPaneIx 

<Button Command="{x:Static custom:Windowl.CustomRoutedCommand}" 
Content="CustomRoutedCommand"/> 

</StackPanel> 


// create the ui 

StackPanel CustomCommandStackPanel = new StackPanel(); 
Button CustomCommandButton = new Button(); 
CustomCommandStackPanel.Children.Add(CustomCommandButton)j 

CustomCommandButton.Command = CustomRoutedCommand; 





' create the ui 

Dim CustomCommandStackPanel As New StackPanelO 
Dim CustomCommandButton As New Button() 
CustomCommandStackPanel.Children.Add(CustomCommandButton) 

CustomCommandButton.Command = CustomRoutedCommand 


When the Button is clicked, the Execute method on the custom RoutedCommand is called. The RoutedCommand 
raises the PreviewExecuted and Executed routed events. These events traverse the element tree looking for a 
CommandBinding for this particular command. If a CommandBinding is found, the ExecutedRoutedEventHandler 
associated with CommandBinding is called. 

See also 

• RoutedCommand 

• Commanding Overview 
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This example shows how to create a command source by implementing ICommandSource. A command source is 
an object that knows how to invoke a command. The ICommandSource interface exposes three members: 

• Command: the command that will be invoked. 

• CommandParameter: a user-defined data type which is passed from the command source to the method that 
handles the command. 

• CommandTarget: the object that the command is being executed on. 

In this example, a class is created that inherits from the Slider control and implements the ICommandSource 
interface. 

Example 

WPF provides a number of classes which implement ICommandSource, such as Button, Menultem, and Hyperlink. 
A command source defines how it invokes a command. These classes invoke a command when they're clicked and 
they only become a command source when their Command property is set. 

In this example, you'll invoke the command when the slider is moved, or more accurately, when the Value property 
is changed. 


The following is the class definition: 


public class CommandSlider : 

: Slider^ ICommandSource 

{ 


public CommandSliderO : 

: base() 

{ 


} 



Public Class CommandSliden 
Inherits Slider 
Implements ICommandSource 
Public Sub New() 

MyBase.NewO 

End Sub 

The next step is to implement the ICommandSource members. In this example, the properties are implemented as 
DependencyProperty objects. This enables the properties to use data binding. For more information about the 
DependencyProperty class, see the Dependency Properties Overview. For more information about data binding, 
see the Data Binding Overview. 


Only the Command property is shown here. 





// Make Command a dependency property so it can use databinding. 
public static readonly DependencyProperty CommandProperty = 
DependencyProperty.Register( 

"Command"j 

typeof(ICommand ), 

typeof(CommandSlider)j 

new PropertyMetadata((ICommand)nullj 

new PropertyChangedCallback(CommandChanged))); 

public ICommand Command 

{ 

get 

{ 

return (ICommand)Get\/alue(CommandProperty); 

} 

set 

{ 

SetValue(CommandPropertyj value); 

} 


' Make Command a dependency property so it can use databinding. 

Public Shared Readonly CommandProperty As DependencyProperty = 

DependencyProperty.Register("Command"j Getlype(ICommand)j 
GetType(CommandSlider)^ 

New PropertyMetadata(CType(Nothing^ ICommand), 

New PropertyChangedCallback(AddressOf CommandChanged))) 

Public Readonly Property Commandl() As ICommand Implements ICommandSource.Command 
Get 

Return CType(Get\/alue(CommandProperty)j ICommand) 

End Get 
End Property 

Public Property Command() As ICommand 
Get 

Return CType(Get\/alue(CommandProperty)j ICommand) 

End Get 

Set(By\/al value As ICommand) 

SetValue(CommandPropertyj value) 

End Set 
End Property 


The following is the DependencyProperty change callback: 

// Command dependency property change callback, 
private static void CommandChanged(DependencyObject d, 

DependencyPropertyChangedEventArgs e) 

{ 

CommandSlider cs = (CommandSlider)d; 

cs.HookUpCommand((ICommand)e.01d\/aluej (ICommand)e.NewValue); 


' Command dependency property change callback. 

Private Shared Sub CommandChanged(By\/al d As DependencyObject, ByVal e As DependencyPropertyChangedEventArgs) 
Dim cs As CommandSlider = CType(dj CommandSlider) 

cs.HookUpCommand(CType(e.01d\/alue, ICommand)^ CType(e.NewValuej ICommand)) 

End Sub 


The next step is to add and remove the command which is associated with the command source. The Command 
property cannot simply be overwritten when a new command is added, because the event handlers associated 




with the previous command, if there was one, must be removed first. 


// Add a new command to the Command Property. 

private void HookUpCommand(ICommand oldCommandj ICommand newCommand) 

{ 

// If oldCommand is not null, then we need to remove the handlers, 
if (oldCommand != null) 

{ 

RemoveCommand(oldCommand, newCommand); 

} 

AddCommand(oldCommand, newCommand); 

} 

// Remove an old command from the Command Property. 

private void RemoveCommand(ICommand oldCommand, ICommand newCommand) 

{ 

EventHandler handler = CanExecuteChanged; 
oldCommand.CanExecuteChanged -= handler; 

} 

// Add the command. 

private void AddCommand(ICommand oldCommand, ICommand newCommand) 

{ 

EventHandler handler = new EventHandler(CanExecuteChanged); 
canExecuteChangedHandler = handler; 
if (newCommand != null) 

{ 

newCommand.CanExecuteChanged += canExecuteChangedHandler; 

} 

} 


' Add a new command to the Command Property. 

Private Sub HookLlpCommand(ByVal oldCommand As ICommand, ByVal newCommand As ICommand) 
' If oldCommand is not null, then we need to remove the handlers. 

If oldCommand IsNot Nothing Then 

RemoveCommand(oldCommand, newCommand) 

End If 

AddCommand(oldCommand, newCommand) 

End Sub 

' Remove an old command from the Command Property. 

Private Sub RemoveCommand(ByVal oldCommand As ICommand, ByVal newCommand As ICommand) 
Dim handler As EventHandler = AddressOf CanExecuteChanged 
RemoveHandler oldCommand.CanExecuteChanged, handler 
End Sub 

' Add the command. 

Private Sub AddCommand(ByVal oldCommand As ICommand, ByVal newCommand As ICommand) 

Dim handler As New EventHandler(AddressOf CanExecuteChanged) 
canExecuteChangedHandler = handler 
If newCommand IsNot Nothing Then 

AddHandler newCommand.CanExecuteChanged, canExecuteChangedHandler 
End If 
End Sub 


The next step is to create logic for the CanExecuteChanged handler. 

The CanExecuteChanged event notifies the command source that the ability of the command to execute on the 
current command target may have changed. When a command source receives this event, it typically calls the 
CanExecute method on the command. If the command cannot execute on the current command target, the 
command source will typically disable itself. If the command can execute on the current command target, the 
command source will typically enable itself 



private void CanExecuteChanged(object sendetj EventArgs e) 

{ 

if (this.Command != null) 

{ 

RoutedCommand command = this.Command as RoutedCommand; 

// If a RoutedCommand. 
if (command != null) 

{ 

if (command.CanExecute(CommandParameterj CommandTarget)) 

{ 

this.IsEnabled = true; 

} 

else 

{ 

this.IsEnabled = false; 

} 

} 

// If a not RoutedCommand. 
else 
{ 

if (Command.CanExecute(CommandParameten)) 

{ 

this.IsEnabled = true; 

} 

else 

{ 

this.IsEnabled = false; 

} 

} 

} 

} 


Private Sub CanExecuteChanged(By\/al sender As Object^ ByVal e As EventArgs) 
If Me.Command IsNot Nothing Then 

Dim command As RoutedCommand = TryCast(Me.Command, RoutedCommand) 

' If a RoutedCommand. 

If command IsNot Nothing Then 

If command.CanExecute(CommandParameter, CommandTarget) Then 
Me.IsEnabled = True 

Else 

Me.IsEnabled = False 
End If 

' If a not RoutedCommand. 

Else 

If Me.Command.CanExecute(CommandParameter) Then 
Me.IsEnabled = True 

Else 

Me.IsEnabled = False 
End If 
End If 
End If 
End Sub 


The last step is the Execute method. If the command is a RoutedCommand, the RoutedCommand Execute method 
is called; otherwise, the ICommand Execute method is called. 



// If Command is defined^ moving the slider will invoke the command; 

// Otherwise, the slider will behave normally. 

protected override void On\/alueChanged(double oldValue, double newValue) 

{ 

base.OnValueChanged(oldValue, newValue); 

if (this.Command != null) 

{ 

RoutedCommand command = Command as RoutedCommand; 

if (command != null) 

{ 

command.Execute(CommandParameter, CommandTarget); 

} 

else 

{ 

((ICommand)Command).Execute(CommandParameter); 

} 

} 

} 


' If Command is defined, moving the slider will invoke the command; 

' Otherwise, the slider will behave normally. 

Protected Overrides Sub OnValueChanged(ByVal oldValue As Double, ByVal newValue As Double) 
MyBase.OnValueChanged(oldValue, newValue) 

If He.Command IsNot Nothing Then 

Dim command As RoutedCommand = TryCast(He.Command, RoutedCommand) 

If command IsNot Nothing Then 

command.Execute(CommandParameter, CommandTarget) 

Else 

CType(Me.Command, ICommand).Execute(CommandParameter) 

End If 
End If 
End Sub 


See also 

• ICommandSource 

• ICommand 

• RoutedCommand 

• Commanding Overview 
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The following example shows how to hook up a RoutedCommand to a Control which does not have built in 
support for the command. For a complete sample which hooks up commands to multiple sources, see the Create a 
Custom RoutedCommand Sample sample. 

Example 

Windows Presentation Foundation (WPF) provides a library of common commands which application 
programmers encounter regularly. The classes which comprise the command library are: ApplicationCommands, 
ComponentCommands, NavigationCommands, MediaCommands, and EditingCommands. 

The static RoutedCommand objects which make up these classes do not supply command logic. The logic for the 
command is associated with the command with a CommandBinding. Many controls in WPF have built in support 
for some of the commands in the command library. TextBox, for example, supports many of the application edit 
commands such as Paste, Copy, Cut, Redo, and Undo. The application developer does not have to do anything 
special to get these commands to work with these controls. If the TextBox is the command target when the 
command is executed, it will handle the command using the CommandBinding that is built into the control. 

The following shows how to use a Button as the command source for the Open command. A CommandBinding is 
created that associates the specified CanExecuteRoutedEventHandler and the CanExecuteRoutedEventHandler with 
the RoutedCommand. 

First, the command source is created. A Button is used as the command source. 


<Button Command="ApplicationCommands.Open" Name="MyButton" 
Height="50" Width="200"> 

Open (KeyBindings: Ctrl+R, Ctrl+0) 

</Button> 


// Button used to invoke the command 
Button CommandButton = new Button(); 

CommandButton.Command = ApplicationCommands.Open; 
CommandButton.Content = "Open (KeyBindings: Ctrl-R, Ctrl-0)"; 
MainStackPanel.Children.Add(CommandButton); 


' Button used to invoke the command 
Dim CommandButton As New Button() 

CommandButton.Command = ApplicationCommands.Open 
CommandButton.Content = "Open (KeyBindings: Ctrl-R, Ctrl-0)" 
MainStackPanel.Children.Add(CommandButton) 


Next, the ExecutedRoutedEventHandler and the CanExecuteRoutedEventHandler are created. The 
ExecutedRoutedEventHandler simply opens a MessageBox to signify that the command executed. The 
CanExecuteRoutedEventHandler sets the CanExecute property to true . Normally, the can execute handler would 
perform more robust checks to see if the command could execute on the current command target. 





void OpenCmdExecuted(object target^ ExecutedRoutedEventArgs e) 

{ 

String commandj targetobj; 

command = ((RoutedCommand)e.Command).Name; 

targetobj = ((Frameworl<Element)target) .Name; 

MessageBox.Show("The " + command + " command has been invoked on target object " + targetobj); 

} 

void OpenCmdCanExecute(object sender^ CanExecuteRoutedEventArgs e) 

{ 

e.CanExecute = true; 

} 


Private Sub OpenCmdExecuted(ByVal sender As Object, ByVal e As ExecutedRoutedEventArgs) 

Dim command, targetobj As String 

command = CType(e.Command, RoutedCommand).Name 

targetobj = CType(sender, FrameworkElement).Name 

MessageBox.Show("The " + command + " command has been invoked on target object " + targetobj) 
End Sub 

Private Sub OpenCmdCanExecute(ByVal sender As Object, ByVal e As CanExecuteRoutedEventArgs) 
e.CanExecute = True 
End Sub 


Finally, a ComnnandBinding is created on the root Window of the application that associates the routed events 
handlers to the Open comnnand. 


<Window.CommandBindings> 

<CommandBinding Command="ApplicationCommands.Open" 
Executed="OpenCmdExecuted" 
CanExecute="OpenCmdCanExecute"/> 
</Window.CommandBindings> 


// Creating CommandBinding and attaching an Executed and CanExecute handler 
CommandBinding OpenCmdBinding = new CommandBinding( 

ApplicationCommands.Open, 

OpenCmdExecuted, 

OpenCmdCanExecute); 

this.CommandBindings.Add(OpenCmdBinding); 


' Creating CommandBinding and attaching an Executed and CanExecute handler 

Dim OpenCmdBinding As New CommandBinding(ApplicationCommands.Open, AddressOf OpenCmdExecuted, AddressOf 
OpenCmdCanExecute) 

Me.CommandBindings.Add(OpenCmdBinding) 


See also 


• Commanding Overview 

• Hook Up a Command to a Control with Command Support 
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The following example shows how to hook up a RoutedCommand to a Control which has built in support for the 
command. For a complete sample which hooks up commands to multiple sources, see the Create a Custom 
RoutedCommand Sample sample. 

Example 

Windows Presentation Foundation (WPF) provides a library of common commands which application 
programmers encounter regularly. The classes which comprise the command library are: ApplicationCommands, 
ComponentCommands, NavigationCommands, MediaCommands, and EditingCommands. 

The static RoutedCommand objects which make up these classes do not supply command logic. The logic for the 
command is associated with the command with a CommandBinding. Some controls have built in 
CommandBindings for some commands. This mechanism allows the semantics of a command to stay the same, 
while the actual implementation is can change. A TextBox, for example, handles the Paste command differently than 
a control designed to support images, but the basic idea of what it means to paste something stays the same. The 
command logic cannot be supplied by the command, but rather must be supplied by the control or the application. 

Many controls in WPF do have built in support for some of the commands in the command library. TextBox, for 
example, supports many of the application edit commands such as Paste, Copy, Cut, Redo, and Undo. The 
application developer does not have to do anything special to get these commands to work with these controls. If 
the TextBox is the command target when the command is executed, it will handle the command using the 
CommandBinding that is built into the control. 

The following shows how to use a Menultem as the command source for the Paste command, where a TextBox is 
the target of the command. All the logic that defines how the TextBox performs the paste is built into the TextBox 
control. 

A Menultem is created and it's Command property is set to the Paste command. The CommandTarget is not 
explicitly set to the TextBox object. When the CommandTarget is not set, the target for the command is the element 
which has keyboard focus. If the element which has keyboard focus does not support the Paste command or 
cannot currently execute the paste command (the clipboard is empty, for example) then the Menultem would be 
grayed out. 




<Window x:Class="SDKSamples.Windowl" 

xtiilns="http: //schemas. micnosoft. com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml" 
Title="MenuItemCommandTask" 

> 

<DockPanel> 

<Menu DockPanel.Dock="Top"> 

<MenuItem Command="AppllcationCommands.Paste" Width="75" /> 
</Menu> 

<TextBox BonderBrush="Black" BonderThickness="2" Margin="25" 
TextWrapping="Wrap"> 

The Menultem will not be enabled until 
this TextBox gets keyboard focus 
</TextBox> 

</DockPanel> 

</Window> 


// Windowl constructor 
public WindowlO 
{ 

InitializeComponentO; 

// Instantiating UIElements. 

DockPanel mainPanel = new DockPanel(); 

Menu mainMenu = new Menu(); 

Menultem pasteMenuItem = new Menultem(); 

TextBox mainTextBox = new TextBox(); 

// Associating the Menultem with the Paste command. 
pasteMenuItem.Command = ApplicationCommands.Paste; 

// Setting properties on the TextBox. 
mainTextBox.Text = 

"The Menultem will not be enabled until this TextBox receives keyboard focus."; 
mainTextBox.Margin = new Thickness(25); 
mainTextBox.BorderBrush = Brushes.Black; 
mainTextBox.BorderThickness = new Thickness(2); 
mainTextBox.Textwrapping = Textwrapping.Wrap; 

// Attaching UIElements to the Window, 
this.AddChild(mainPanel); 
mainMenu.Items.Add(pasteMenuItem); 
mainPanel.Children.Add(mainMenu); 
mainPanel.Children.Add(mainTextBox); 

// Defining DockPanel layout. 

DockPanel.SetDock(mainMenuj Dock.Top); 

DockPanel.SetDock(mainTextBoXj Dock.Bottom); 



' Windowl constructor 
Public Sub New() 

InitializeComponentO 

' Instantiating UIElements. 

Dim mainPanel As New DockPanel() 

Dim mainMenu As New Menu() 

Dim pasteMenuItem As New Menultem() 

Dim mainTextBox As New TextBox() 

' Associating the Menultem with the Paste command. 
pasteMenuItem.Command = ApplicationCommands.Paste 

' Setting properties on the TextBox. 

mainTextBox.Text = "The Menultem will not be enabled until this TextBox receives keyboard focus. 

mainTextBox.Margin = New Thickness(25) 

mainTextBox.BorderBrush = Brushes.Black 

mainTextBox.BorderThickness = New Thickness(2) 

mainTextBox.Textwrapping = Textwrapping.Wrap 

' Attaching UIElements to the Window. 

Me.AddChild(mainPanel) 
mainMenu.Items.Add(pasteMenuItem) 
mainPanel.Children.Add(mainMenu) 
mainPanel.Children.Add(mainTextBox) 

' Defining DockPanel layout. 

DockPanel.SetDock(mainMenu^ Dock.Top) 

DockPanel.SetDock(mainTextBox, Dock.Bottom) 

End Sub 


See also 


• Commanding Overview 

• Hook Up a Command to a Control with No Command Support 
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This section discusses the use of digital ink in the WPF. Traditionally found only in the Tablet PC SDK, digital ink is 
now available in the core Windows Presentation Foundation. This means you can now develop full-fledged Tablet 
PC applications by using the power of Windows Presentation Foundation. 

In This Section 

Overviews 
How-to Topics 

Related Sections 

Windows Presentation Foundation 
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In This Section 

Getting Started with Ink 
Collecting Ink 
Handwriting Recognition 
Storing Ink 

The Ink Object Model: Windows Forms and COM versus WPF 
Advanced Ink Handling 
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Windows Presentation Foundation (WPF) has an ink feature that makes it easy to incorporate digital ink into your 
app. 


Prerequisites 

To use the following examples, first install Visual Studio. It also helps to know how to write basic WPF apps. For 
help getting started with WPF, see Walkthrough: My first WPF desktop application. 

Quick Start 

This section helps you write a simple WPF application that collects ink. 

Got Ink? 

To create a WPF app that supports ink: 

1. Open Visual Studio. 

2. Create a new WPF App. 

In the New Project dialog, expand the Installed > Visual C# or Visual Basic > Windows Desktop 
category. Then, select the WPF App (.NET Framework) app template. Enter a name, and then select OK. 

Visual Studio creates the project, and MainWindow.xamlopens in the designer. 

















4. Press F5 to launch your application in the debugger. 


5. Using a stylus or mouse, write hello world in the window. 

You've written the ink equivalent of a "hello world" application with only 12 keystrokes! 

Spice Up Your App 

Let's take advantage of some features of the WPF. Replace everything between the opening and closing 
<Window> tags with the following markup: 

<Page> 

<InkCanvas Name="myInkCanvas" MouseRightButtonLlp="RightMouseUpHandler"> 

<InkCanvas.Background) 

<LinearGradientBrush) 

<GradientStop Color="Yellow" Offset="0.0" /) 

<GradientStop Color="Blue" Offset="0.5" /) 

<GradientStop Color="HotPink" Offset="1.0" /) 

</LinearGradientBrush) 

</InkCanvas.Background) 

</InkCanvas) 

</Page) 


This XAML creates a gradient brush background on your inking surface. 



Add Some Code Behind the XAML 

While XAML makes it very easy to design the user interface, any real-world application needs to add code to 
handle events. Here is a simple example that zooms in on the inkin response to a right-click from a mouse. 

1. Set the MouseRightButtonUp handler in your XAML: 

<InkCanvas Name="myInkCanvas" HouseRightButtonLlp="RightMouseLlpHandler") 


2. In Solution Explorer, expand MainWindow.xamI and open the code-behind file (MainWindow.xaml.cs or 
MainWindow.xaml.vb). Add the following event handler code: 

private void RightMouseLlpHandler(object sender. 

System.Windows.Input.MouseButtonEventArgs e) 

{ 

Matrix m = new Matrix(); 
m.Scale(l.ld, l.ld); 

((InkCanvas)sender).Strokes.Transform(m, true); 










Private Sub RightMouseUpHandler(ByVal sender As Object, _ 

ByVal e As System.Windows.Input.MouseButtonEventArgs) 

Dim m As New Matrix() 
m.Scale(l.l, 1.1) 

CType(sender, InkCanvas).Strokes.Transform(m, True) 

End Sub 


3. Run the application. Add some ink, and then right-click with the mouse or perform a press-and-hold 
equivalent with a stylus. 

The display zooms in each time you click with the right mouse button. 

Use Procedural Code Instead of XAML 

You can access all WPF features from procedural code. Follow these steps to create a "Hello Ink World" application 
for WPF that doesn't use any XAML at all. 

1. Create a new console application project in Visual Studio. 

In the New Project dialog, expand the Installed > Visual C# or Visual Basic > Windows Desktop 
category. Then, select the Console App (.NET Framework) app template. Enter a name, and then select 
OK. 

2. Paste the following code into the Program.es or Program.vb file: 

using System; 

using System.Windows; 

using System.Windows.Controls; 

class Program : Application 

{ 

Window win; 

InkCanvas ic; 

protected override void OnStartup(StartupEventArgs args) 

{ 

base.OnStartup(args); 
win = new Window(); 
ic = new InkCanvas(); 
win.Content = ic; 
win.ShowO; 

} 

[STAThread] 

static void Main(string[] args) 

{ 

new ProgramO .Run(); 

} 

} 




Imports System.Windows 
Imports System.Windows.Controls 


Class Program 

Inherits Application 
Private win As Window 
Private ic As InkCanvas 


Protected Overrides Sub OnStartup(ByVal args As StartupEventArgs) 
MyBase.OnStartup(args) 
win = New Window() 
ic = New InkCanvasO 
win.Content = ic 
win.ShowO 

End Sub 

End Class 

Module Modulel 
Sub Main() 

Dim prog As New Program() 
prog.Run() 

End Sub 

End Module 


3. Add references to the PresentationCore, PresentationFramework, and WindowsBase assemblies by ri 
clicking on References in Solution Explorer and choosing Add Reference. 



4. Build the application by pressing F5. 

See also 

• Digital Ink 

• Collecting Ink 

• Handwriting Recognition 

• Storing Ink 
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The Windows Presentation Foundation platform collects digital ink as a core part of its functionality. This topic 
discusses methods for collection of ink in Windows Presentation Foundation (WPF). 

Prerequisites 

To use the following examples, you must first install Visual Studio and the Windows SDK. You should also 
understand how to write applications for the WPF. For more information about getting started with WPF, see 
Walkthrough: My first WPF desktop application. 

Use the InkCanvas Element 

The System.Windows.Controls.InkCanvas element provides the easiest way to collect ink in WPF. Use an InkCanvas 
element to receive and display ink input. You commonly input ink through the use of a stylus, which interacts with 
a digitizer to produce ink strokes. In addition, a mouse can be used in place of a stylus. The created strokes are 
represented as Stroke objects, and they can be manipulated both programmatically and by user input. The 
InkCanvas enables users to select, modify, or delete an existing Stroke. 

By using XAML, you can set up ink collection as easily as adding an InkCanvas element to your tree. The following 
example adds an InkCanvas to a default WPF project created in Visual Studio: 

<Grid> 

<Inl<Canvas/> 

</Gr'id> 

The InkCanvas element can also contain child elements, making it possible to add ink annotation capabilities to 
almost any type of XAML element. For example, to add inking capabilities to a text element, simply make it a child 
of an InkCanvas: 

<Inl<Canvas> 

<TextBlocl<>Show text her'e.</TextBlock> 

</InkCanvas> 

Adding support for marking up an image with ink is just as easy: 

<InkCanvas> 

<Image Source="myPicture.jpg"/> 

</InkCanvas> 

InkCollection Modes 

The InkCanvas provides support for various input modes through its EditingMode property. 

Manipulate Ink 

The InkCanvas provides support for many ink editing operations. For example, InkCanvas supports back-of-pen 
erase, and no additional code is needed to add the functionality to the element. 

Selection 

Setting selection mode is as simple as setting the InkCanvasEditingMode property to Select. 







The following code sets the editing mode based on the value of a CheckBox: 



' Set the selection mode based on a checkbox 
If CBool(cbSelectionMode.IsChecked) Then 

theInkCanvas.EditingMode = InkCanvasEditingMode.Select 

Else 

theInkCanvas.EditingMode = InkCanvasEditingMode.Ink 
End If 

DrawingAttributes 

Use the DrawingAttributes property to change the appearance of ink strokes. For instance, the Color member of 
DrawingAttributes sets the color of the rendered Stroke. 

The following example changes the color of the selected strokes to red: 

// Get the selected strokes from the InkCanvas 
StrokeCollection selection = theInkCanvas.GetSelectedStrokes()j 

// Check to see if any strokes are actually selected 
if (selection.Count > 0) 

{ 

// Change the color of each stroke in the collection to red 
foreach (System.Windows.Ink.Stroke stroke in selection) 

{ 

stroke.DrawingAttributes.Color = System.Windows.Media.Colors.Red; 

} 

} 


' Get the selected strokes from the InkCanvas 

Dim selection As StrokeCollection = theInkCanvas.GetSelectedStrokes() 

' Check to see if any strokes are actually selected 
If selection.Count > 0 Then 

' Change the color of each stroke in the collection to red 
Dim stroke As System.Windows.Ink.Stroke 
For Each stroke In selection 

stroke.DrawingAttributes.Color = System.Windows.Media.Colors.Red 
Next stroke 
End If 


DefaultDrawingAttributes 

The DefaultDrawingAttributes property provides access to properties such as the height, width, and color of the 
strokes to be created in an InkCanvas. Once you change the DefaultDrawingAttributes, all future strokes entered 
into the InkCanvas are rendered with the new property values. 

In addition to modifying the DefaultDrawingAttributes in the code-behind file, you can use XAML syntax for 
specifying DefaultDrawingAttributes properties. 

The next example demonstrates how to set the Color property. To use this code, create a new WPF project called 




"HelloInkCanvas" in Visual Studio. Replace the code in the MainWindow.xamI f\\e with the following code: 

<Window X:Class="HelloInkCanvas.Windowl" 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 

xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

xmlns:Ink="cln-namespace:System.Windows.Ink;assembly=PresentationCore" 

Title="Hello, InkCanvas!" Height="300" Width="300" 

> 

<Grid> 

<InkCanvas Name="inkCanvasl" Background="Ivory"> 

<InkCanvas.DefaultDnawingAttributes> 

<Ink:DrawingAttributes xmlns:ink="system-windows-ink" Colon="Red" Width="5" /> 

</InkCanvas.DefaultDnawingAttributesx 
</InkCanvas> 

<!-- This stack panel of buttons is a sibling to InkCanvas (not a child) but overlapping it^ 
higher in z-order^ so that ink is collected and rendered behind --> 

<StackPanel Name="buttonBar" VerticalAlignment="Top" Height="26" Orientation="Horizontal" Margin="5"> 
<Button Click="Ink">Ink</Button> 

<Button Click="Highlight">Highlight</Button> 

<Button Clicks"EraseStroke">EraseStroke</Button> 

<Button Click="Select">Select</Button> 

</StackPanel> 

</Grid> 

</Window> 


Next, add the following button event handlers to the code behind file, inside the MainWindow class: 

// Set the EditingMode to ink input. 

private void Ink(object sender^ RoutedEventArgs e) 

{ 

inkCanvasl.EditingMode = InkCanvasEditingMode.Ink; 

// Set the DefaultDrawingAttributes for a red pen. 
inkCanvasl.DefaultDrawingAttributes.Color = Colors.Red; 
inkCanvasl.DefaultDrawingAttributes.IsHighlighter = false; 
inkCanvasl.DefaultDrawingAttributes.Height = 2; 


// Set the EditingMode to highlighter input. 

private void Highlight(object sender, RoutedEventArgs e) 

{ 

inkCanvasl.EditingMode = InkCanvasEditingMode.Ink; 

// Set the DefaultDrawingAttributes for a highlighter pen. 
inkCanvasl.DefaultDrawingAttributes.Color = Colors.Yellow; 
inkCanvasl.DefaultDrawingAttributes.IsHighlighter = true; 
inkCanvasl.DefaultDrawingAttributes.Height = 25; 

} 

// Set the EditingMode to erase by stroke. 

private void EraseStroke(object sender, RoutedEventArgs e) 

{ 

inkCanvasl.EditingMode = InkCanvasEditingMode.EraseByStroke; 

} 

// Set the EditingMode to selection. 

private void Select(object sender, RoutedEventArgs e) 

{ 

inkCanvasl.EditingMode = InkCanvasEditingMode.Select; 

} 


After copying this code, press F5 in Visual Studio to run the program in the debugger. 

Notice how the StackPanel places the buttons on top of the InkCanvas. If you try to ink over the top of the buttons. 




the InkCanvas collects and renders the ink behind the buttons. This is because the buttons are siblings of the 
InkCanvas as opposed to children. Also, the buttons are higher in the z-order, so the ink is rendered behind them. 


See also 

• DrawingAttributes 

• DefaultDrawingAttributes 

• System.Windows.Ink 
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This section discusses the fundamentals of recognition as it pertains to digital ink in the WPF platform. 

Recognition Solutions 

The following example shows how to recognize ink using the Microsoft.Ink.InkCollector class. 


NOTE 

This sample requires that handwriting recognizers be installed on the system. 


Create a new WPF application project in Visual Studio called InkRecognition. Replace the contents of the 
Windowl .xami file with the following XAML code. This code renders the application's user interface. 

<Window x:Class="InkRecognition.Windowl" 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

Title="InkRecognition" 

> 

<Canvas Name="theRootCanvas"> 

<Border 

Backgnound="White" 

BordenBnush="Black" 

BorderThickness="2" 

Height="300" 

Wldth="300" 

Canvas.Top="10" 

Canvas.Left="10"> 

<InkCanvas IMame="theInkCanvas"></InkCanvas> 

</Borden> 

clextBox Name="textBoxl" 

Height="25" 

Width="225" 

Canvas.Top="325" 

Canvas.Left="10"></TextBox> 

<Button 

Height="25" 

Width="75" 

Canvas.Top="325" 

Canvas.Left="235" 

Click="buttonClick">Recognize</Button> 

<Button x:Name="btnClean" Content="Clear Canvas" Canvas.Left="10" Canvas.Top="367" Width="75" 
Click="btnClear_Click"/> 

</Canvas> 

</Window> 


Add a reference to the Microsoft Ink assembly, Microsoft.lnk.dll, which can be found in \Program Files\Common 
Files\Microsoft Shared\lnk. Replace the contents of the code behind file with the following code. 






using System.Windows; 
using Microsoft.Ink; 
using System.10; 

namespace InkRecognition 

{ 

III <summary> 

III Interaction logic for Windowl.xaml 
III </summary> 

public partial class Windowl : Window 

{ 

public WindowlO 

{ 

InitializeComponentO; 

} 

// Recognizes handwriting by using RecognizerContext 
private void buttonClick(object sender^ RoutedEventArgs e) 

{ 

using (MemoryStream ms = new MemoryStream()) 

{ 

theInkCanvas.Strokes.Save(ms); 
var myInkCollector = new InkCollector(); 
var ink = new Ink(); 
ink.Load(ms.ToArray()); 

using (RecognizerContext context = new RecognizerContext()) 

{ 

if (ink.Strokes.Count > 0) 

{ 

context.Strokes = ink.Strokes; 

RecognitionStatus status; 

var result = context.Recognize(out status); 

if (status == RecognitionStatus.NoError) 
textBoxl.Text = result.TopString; 

else 

MessageBox.Show("Recognition failed"); 

} 

else 

{ 

MessageBox.Show("No stroke detected"); 

} 

} 

} 

} 

private void btnClear_Click(object sender, RoutedEventArgs e) { 
theInkCanvas.Strokes.Clear(); 

} 

} 

} 



Imports System.Windows 
Imports Microsoft.Ink 
Imports System.10 

'/ <summary> 

'/ Interaction logic for Windowl.xaml 
'/ </summary> 

Namespace InkRecognition 

Class Windowl 

Inherits Window 

Public Sub New() 

InitializeComponentO 
End Sub 


' Recognizes handwriting by using RecognizerContext 

Private Sub buttonClick(By\/al sender As Object^ ByVal e As RoutedEventArgs) 

Using ms As New MemoryStream() 
theInkCanvas.Strokes.Save(ms) 

Dim myInkCollector As InkCollector = New InkCollector() 

Dim ink As Ink = New Ink() 
ink.Load(ms.ToArray()) 

Using context As New RecognizerContext() 

If ink.Strokes.Count > 0 Then 

context.Strokes = ink.Strokes 
Dim status As RecognitionStatus 

Dim result As RecognitionResult = context.Recognize(status) 

If status = RecognitionStatus.NoError Then 
textBoxl.Text = result.TopString 

Else 

MessageBox.Show("Recognition failed") 

End If 

Else 

MessageBox.Show("No stroke detected") 

End If 
End Using 
End Using 
End Sub 

Private Sub btnClear_Click(sender As Object, e As RoutedEventArgs) 
theInkCanvas.Strokes.Clear() 

End Sub 
End Class 
End Namespace 


See also 


• Microsoft.Ink.InkCollector 
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The Save methods provide support for storing ink as Ink Serialized Format (ISF). Constructors for the 
StrokeCollection class provide support for reading ink data. 

Ink Storage and Retrieval 

This section discusses how to store and retrieve ink in the WPF platform. 

The following example implements a button-click event handler that presents the user with a File Save dialog box 
and saves the ink from an InkCanvas out to a file. 


private void buttonSaveAsClick(object sendetj RoutedEventArgs e) 

{ 

SaveFileDialog saveFileDialogl = new SaveFileDialogO; 
saveFileDialogl.Filter = "isf files (*.isf)|*.isf"j 

if (saveFileDialogl.ShowDialogO == true) 

{ 

FileStream fs = new FileStream(saveFileDialogl.FileName, 

FileMode.Create); 

theInkCanvas.Strokes.Save(fs); 
fs.CloseO; 

} 


Private Sub buttonSaveAsClick(ByVal sender As Object^ ByVal e As RoutedEventArgs) 

Dim saveFileDialogl As New SaveFileDialogO 
saveFileDialogl.Filter = "isf files (*.isf)|*.isf" 

If saveFileDialogl.ShowDialogO Then 

Dim fs As New FileStream(saveFileDialogl.FileName, FileMode.Create) 
theInkCanvas.Strokes.Save(fs) 
fs.CloseO 
End If 

End Sub 


The following example implements a button-click event handler that presents the user with a File Open dialog box 
and reads ink from the file into an InkCanvas element. 





private void buttonLoadClicl<(object sender, RoutedEventArgs e) 

{ 

OpenFileDialog openFileDialogl = new OpenFileDialogO; 
openFileDialogl.Filter = "isf files (*.isf)|*.isf"j 

if (openFileDialogl.ShowDialogO == true) 

{ 

FileStream fs = new FileStream(openFileDialogl.FileName, 

FileMode.Open); 

theInkCanvas.Strokes = new StrokeCollection(fs); 
fs.CloseO; 

} 


Private Sub buttonLoadClick(By\/al sender As Object, ByVal e As RoutedEventArgs) 

Dim openFileDialogl As New OpenFileDialogO 
openFileDialogl.Filter = "isf files (*.isf)|*.isf" 

If openFileDialogl.ShowDialogO Then 

Dim fs As New FileStream(openFileDialogl.FileName, FileMode.Open) 
theInkCanvas.Strokes = New StrokeCollection(fs) 
fs.CloseO 
End If 

End Sub 


See also 

• InkCanvas 

• Windows Presentation Foundation 
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There are essentially three platforms that support digital ink: the Tablet PC Windows Forms platform, the Tablet PC 
COM platform, and the Windows Presentation Foundation (WPF) platform. The Windows Forms and COM 
platforms share a similar object model, but the object model for the WPF platform is substantially different. This 
topic discusses the differences at a high-level so that developers that have worked with one object model can 
better understand the other. 

Enabling Ink in an Application 

All three platforms ship objects and controls that enable an application to receive input from a tablet pen. The 
Windows Forms and COM platforms ship with Microsoft.Ink.InkPicture, Microsoft.Ink.InkEdit, 
Microsoft.Ink.InkOverlay and Microsoft.Ink.InkCollector classes. Microsoft.Ink.InkPicture and Microsoft.Ink.InkEdit 
are controls that you can add to an application to collect ink. The Microsoft.Ink.InkOverlay and 
Microsoft.Ink.InkCollector can be attached to an existing window to ink-enable windows and custom controls. 

The WPF platform includes the InkCanvas control. You can add an InkCanvas to your application and begin 
collecting ink immediately. With the InkCanvas, the user can copy, select, and resize ink. You can add other controls 
to the InkCanvas, and the user can handwrite over those controls, too. You can create an ink-enabled custom 
control by adding an InkPresenter to it and collecting its stylus points. 

The following table lists where to learn more about enabling ink in an application: 


TO DO THIS... 

ON THE WPF PLATFORM... 

ON THE WINDOWS FORMS/COM 

PLATFORMS- 

Add an ink-enabled control to an 
application 

See Getting Started with Ink. 

See Auto Claims Form Sample 

Enable ink on a custom control 

See Creating an Ink Input Control. 

See Ink Clipboard Sample. 


Ink Data 

On the Windows Forms and COM platforms, Microsoft.Ink.InkCollector, Microsoft.Ink.InkOverlay, 
Microsoft.Ink.InkEdit, and Microsoft.Ink.InkPicture each expose a Microsoft.Ink.Ink object. The Microsoft.Ink.Ink 
object contains the data for one or more Microsoft.Ink.Stroke objects and exposes common methods and 
properties to manage and manipulate those strokes. The Microsoft.Ink.Ink object manages the lifetime of the 
strokes it contains; the Microsoft.Ink.Ink object creates and deletes the strokes that it owns. Each 
Microsoft.Ink.Stroke has an identifier that is unique within its parent Microsoft.Ink.Ink object. 

On the WPF platform, the System.Windows.Ink.Stroke class owns and manages its own lifetime. A group of Stroke 
objects can be collected together in a StrokeCollection, which provides methods for common ink data management 
operations such as hit testing, erasing, transforming, and serializing the ink. A Stroke can belong to zero, one, or 
more StrokeCollection objects at any give time. Instead of having a Microsoft.Ink.Ink object, the InkCanvas and 
InkPresenter contain a System.Windows.Ink.StrokeCollection. 

The following pair of illustrations compares the ink data object models. On the Windows Forms and COM 
platforms, the Microsoft.Ink.Ink object constrains the lifetime of the Microsoft.Ink.Stroke objects, and the stylus 




packets belong to the individual strokes. Two or more strokes can reference the same 
Microsoft.Ink.DrawingAttributes object, as shown in the following illustration. 


Ink 



Stroke Id = 1 

DrawingAttrlbutes 


Stylus Packets 


DrawingAttrlbutes 


Stroke Id = 2 

Stylus Packets 


Stroke Id = 3 

Stylus Packets 


On the WPF, each System.Windows.Ink.Stroke is a common language runtime object that exists as long as 
something has a reference to it. Each Stroke references a StylusPointCollection and 
System.Windows.Ink.DrawingAttributes object, which are also common language runtime objects. 



The following table compares how to accomplish some common tasks on the WPF platform and the Windows 
Forms and COM platforms. 


TASK 

WINDOWS PRESENTATION 

EOUNDATION 

WINDOWS FORMS AND COM 

Save ink 

Save 

Microsoft.Ink.Ink.Save 

Load Ink 

Create a StrokeCollection with the 

StrokeCollection constructor. 

Microsoft.Ink.Ink.Load 

Hit test 

HitTest 

M icrosoft. 1 n k. 1 n k. H itTest 

Copy Ink 

CopySelection 

Microsoft.Ink.Ink.ClipboardCopy 

Paste ink 

Paste 

Microsoft.Ink.Ink.ClipboardPaste 


Access custom properties on a AddPropertyData (the properties are Use 

collection of strokes stored internally and accessed via Microsoft.Ink.Ink.ExtendedProperties 

AddPropertyData, 

RemovePropertyData, and 
ContainsPropertyData) 

Sharing ink between platforms 

Although the platforms have different object models for the ink data, sharing the data between the platforms is 
very easy. The following examples save ink from a Windows Forms application and load the ink into a Windows 
Presentation Foundation application. 












































using Microsoft.Ink; 
using System.Drawing; 


Imports Microsoft.Ink 
Imports System.Drawing 


III <summary> 

III Saves the digital ink from a Windows Forms application. 

Ill </summary> 

III <param name="inkToSave">An Ink object that contains the 
III digital ink.</param> 

III <returns>A MemoryStream containing the digital ink.</returns> 
MemoryStream SaveInkInWinforms(Ink inkToSave) 

{ 

byte[] savedink = inkToSave.Save(); 
return (new MemoryStream(savedlnk)); 

} 


'/ <summary> 

'/ Saves the digital ink from a Windows Forms application. 

'/ </summary> 

'/ <param name="inkToSave">An Ink object that contains the 
'/ digital ink.</param> 

'/ <returns>A MemoryStream containing the digital ink.</returns> 
Function SaveInkInWinforms(ByVal inkToSave As Ink) As MemoryStream 
Dim savedink As Byte() = inkToSave.Save() 

Return Mew MemoryStream(savedlnk) 

End Function 'SaveInkInWinforms 



III <summary> 

III Loads digital ink into a StrokeCollectionj which can be 
III used by a WPF application. 

Ill </summary> 

III <param name="savedInk">A MemoryStream containing the digital ink.</param> 
public void LoadInkInWPF(MemoryStream inkStream) 

{ 

strokes = new StrokeCollection(inkStream); 

} 



'/ <summary> 

'/ Loads digital ink into a StrokeCollectionj which can be 
'/ used by a WPF application. 

'/ </summary> 

'/ <param name="savedInk">A MemoryStream containing the digital ink.</panam> 
Public Sub LoadInkInWPF(By\/al inkStneam As MemoryStream) 
strokes = New StrokeCollection(inkStream) 

End Sub 


The following examples save ink from a Windows Presentation Foundation application and load the ink into a 
Windows Forms application. 

using System.Windows.Ink; 


Imports System.Windows.Ink 


III <summary> 

III Saves the digital ink from a WPF application. 

Ill </summary> 

III <param name="inkToSave">A StrokeCollection that contains the 
III digital ink.</param> 

III <returns>A MemoryStream containing the digital ink.</returns> 
MemoryStream SaveInkInWPF(StrokeCollection strokesToSave) 

{ 

MemoryStream savedink = new MemoryStream(); 
strokesToSave.Save(savedink); 
return savedink; 

} 


'/ <summary> 

'/ Saves the digital ink from a WPF application. 

'/ </summary> 

'/ <param name="inkToSave">A StrokeCollection that contains the 
'/ digital ink.</param> 

'/ <returns>A MemoryStream containing the digital ink.</returns> 

Function SaveInkInWPF(ByVal strokesToSave As StrokeCollection) As MemoryStream 
Dim savedink As New MemoryStream() 

strokesToSave.Save(savedink) 

Return savedink 

End Eunction 'SaveInkInWPF 


using Microsoft.Ink; 
using System.Drawing; 


Imports Microsoft.Ink 
Imports System.Drawing 






Ill <summary> 

III Loads digital ink into a Windows Forms application. 

Ill </summary> 

III <param name="savedInk">A MemoryStream containing the digital ink.</param> 
public void LoadInkInWinforms(MemoryStream savedink) 

{ 

theink = new Ink(); 

theink.Load(savedInk.ToArray()); 

} 


'/ <summary> 

'/ Loads digital ink into a Windows Forms application. 

'/ </summary> 

'/ <param name="savedInk">A MemoryStream containing the digital ink.</param> 
Public Sub LoadInkInWinforms(ByVal savedink As MemoryStream) 
theink = New Ink() 
theink.Load(savedInk.ToArray()) 

End Sub 


Events from the Tablet Pen 

The Microsoft.Ink.InkOverlay, Microsoft.Ink.InkCollector, and MicrosoftInk.InkPicture on the Windows Forms and 
COM platforms receive events when the user inputs pen data. The Microsoft.Ink.InkOverlay or 
Microsoft.Ink.InkCollector is attached to a window or a control, and can subscribe to the events raised by the tablet 
input data. The thread on which these events occurs depends on whether the events are raised with a pen, a mouse, 
or programmatically. For more information about threading in relation to these events, see General Threading 
Considerations and Threads on Which an Event Can Fire. 


On the Windows Presentation Foundation platform, the UlElement class has events for pen input. This means that 
every control exposes the full set of stylus events. The stylus events have tunneling/bubbling event pairs and 
always occur on the application thread. For more information, see Routed Events Overview. 


The following diagram shows compares the object models for the classes that raise stylus events. The Windows 
Presentation Foundation object model shows only the bubbling events, not the tunneling event counterparts. 


Windows Forms/COM 
Platforms 

MIcrosoft.Ink 

InkOverlay 

CursorDown 

NewPackets 

CursorUp 

CursorInRange 
CursorOutOf Range 
NewInAirPackets 


Windows Presentation 
Foundation Platform 

System. Windows 
UlElement 
StylusDown 
StylusMove 
StylusUp 
StylusEnter 
Sty I us Leave 
StylusInRange 
Sty I usOutOfRa n g e 
StylusInAirMove 


Pen Data 

All three platforms provide you with ways to intercept and manipulate the data that comes in from a tablet pen. On 
the Windows Forms and COM Platforms, this is achieved by creating a MicrosoftStylusInput.RealTimeStylus, 
attaching a window or control to it, and creating a class that implements the 

Microsoft.StylusInput.lStylusSyncPIugin or Microsoft.StylusInput.lStylusAsyncPIugin interface. The custom plug-in is 
then added to the plug-in collection of the Microsoft.StylusInput.RealTimeStylus. For more information about this 
object model, see Architecture of the Stylusinput APIs. 




On the WPF platform, the UlElement class exposes a collection of plug-ins, similar in design to the 
Microsoft.StylusInput.RealTimeStylus. To intercept pen data, create a class that inherits from StylusPlugIn and add 
the object to the StylusPlugIns collection of the UlElement. For more information about this interaction, see 
Intercepting Input from the Stylus. 

On all platforms, a thread pool receives the ink data via stylus events and sends it to the application thread. For 
more information about threading on the COM and Windows Platforms, see Threading Considerations for the 
Stylusinput APIs. For more information about threading on the Windows Presentation Software, see The Ink 
Threading Model. 


The following illustration compares the object models for the classes that receive pen data on the pen thread pool. 
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The WPF ships with the InkCanvas, and is an element you can put in your application to immediately start 
collecting and displaying ink. However, if the InkCanvas control does not provide a fine enough level of control, 
you can maintain control at a higher level by customizing your own ink collection and ink rendering classes using 
System.Windows.Input.StylusPlugIns. 

The System.Windows.Input.StylusPlugIns classes provide a mechanism for implementing low-level control over 
Stylus input and dynamically rendering ink. The StylusPlugIn class provides a mechanism for you to implement 
custom behavior and apply it to the stream of data coming from the stylus device for optimal performance. The 
DynamicRenderer, a specialized StylusPlugIn, allows you to customize dynamically rendering ink data in real-time 
which means that the DynamicRenderer draws digital ink immediately as StylusPoint data is generated, so it 
appears to "flow" from the stylus device. 

In This Section 

Custom Rendering Ink 
Intercepting Input from the Stylus 
Creating an Ink Input Control 
The Ink Threading Model 
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The DrawingAttributes property of a stroke allows you to specify the appearance of a stroke, such as its size, color, 
and shape, but there may be times that you want to customize the appearance beyond what DrawingAttributes 
allow. You may want to customize the appearance of ink by rendering in the appearance of an air brush, oil paint, 
and many other effects. The Windows Presentation Foundation (WPF) allows you to custom render ink by 
implementing a custom DynamicRenderer and Stroke object. 

This topic contains the following subsections: 

• Architecture 

• Implementing a Dynamic Renderer 

• Implementing Custom Strokes 

• Implementing a Custom InkCanvas 

• Conclusion 

Architecture 

Ink rendering occurs two times; when a user writes ink to an inking surface, and again after the stroke is added to 
the ink-enabled surface. The DynamicRenderer renders the ink when the user moves the tablet pen on the digitizer, 
and the Stroke renders itself once it is added to an element. 

There are three classes to implement when dynamically rendering ink. 

1. DynamicRenderer: Implement a class that derives from DynamicRenderer. This class is a specialized 
StylusPlugIn that renders the stroke as it is drawn. The DynamicRenderer does the rendering on a separate 
thread, so the inking surface appears to collect ink even when the application user interface (Ul) thread is 
blocked. For more information about the threading model, see The Ink Threading Model. To customize 
dynamically rendering a stroke, override the OnDraw method. 

2. Stroke: Implement a class that derives from Stroke. This class is responsible for static rendering of the 
StylusPoint data after it has been converted into a Stroke object. Override the DrawCore method to ensure 
that static rendering of the stroke is consistent with dynamic rendering. 

3. InkCanvas: Implement a class that derives from InkCanvas. Assign the customized DynamicRenderer to the 
DynamicRenderer property. Override the OnStrokeCollected method and add a custom stroke to the Strokes 
property. This ensures that the appearance of the ink is consistent. 

Implementing a Dynamic Renderer 

Although the DynamicRenderer class is a standard part of WPF, to perform more specialized rendering, you must 
create a customized dynamic renderer that derives from the DynamicRenderer and override the OnDraw method. 

The following example demonstrates a customized DynamicRenderer that draws ink with a linear gradient brush 
effect. 




using System; 

using System.Windows.Media; 
using System.Windows; 

using System.Windows.Input.StylusPlugIns; 
using System.Windows.Input; 
using System.Windows.Ink; 


Imports System.Windows.Media 
Imports System.Windows 

Imports System.Windows.Input.StylusPlugIns 
Imports System.Windows.Input 
Imports System.Windows.Ink 


// A StylusPlugin that renders ink with a linear gradient brush effect, 
class CustomDynamicRenderer : DynamicRenderer 
{ 

[ThreadStatic] 

static private Brush brush = null; 

[ThreadStatic] 

static private Pen pen = null; 
private Point prevPoint; 

protected override void OnStylusDown(RawStylusInput rawStylusInput) 

{ 

// Allocate memory to store the previous point to draw from. 
prevPoint = new Point(double.Negativeinfinity, double.Negativeinfinity) 
base.OnStylusDown(rawStylusInput); 

} 

protected override void OnDraw(DrawingContext drawingContextj 

StylusPointCollection stylusPoints, 

Geometry geometry^ Brush fillBrush) 

{ 

// Create a new Brushy if necessary. 

brush ??= new LinearGradientBrush(Colors.Redj Colors.Blue, 20d); 

// Create a new Pen, if necessary, 
pen ??= new Pen(brush, 2d); 

// Draw linear gradient ellipses between 
// all the StylusPoints that have come in. 
for (int i = 0; i < stylusPoints.Count; i++) 

{ 

Point pt = (Point)stylusPoints[i]; 

Vector V = Point.Subtract(prevPoint, pt); 

// Only draw if we are at least 4 units away 
// from the end of the last ellipse. Otherwise, 

// we're just redrawing and wasting cycles, 
if (v.Length > 4) 

{ 

// Set the thickness of the stroke based 
// on how hard the user pressed. 

double radius = stylusPoints[i].PressureFactor * 10d; 
drawingContext.DrawEllipse(brush, pen, pt, radius, radius); 
prevPoint = pt; 


} 



' A StylusPlugin that renders ink with a linear gradient brush effect. 

Class CustomDynamicRenderer 
Inherits DynamicRenderer 
<ThreadStatic()> _ 

Private Shared brush As Brush = Nothing 

<ThreadStatic()> _ 

Private Shared pen As Pen = Nothing 

Private prevPoint As Point 

Protected Overrides Sub OnStylusDown(ByVal rawStylusInput As RawStylusInput) 
' Allocate memory to store the previous point to draw from. 
prevPoint = New Point(Double.NegativeInfinityj Double.Negativeinfinity) 
MyBase.OnStylusDown(rawStylusInput) 

End Sub 


Protected Overrides Sub OnDraw(ByVal drawingContext As DrawingContext, _ 

ByVal stylusPoints As StylusPointCollectionj 
ByVal geometry As Geometry, _ 

ByVal fillBrush As Brush) 

' Create a new Brush, if necessary. 

If brush Is Nothing Then 

brush = New LinearGradientBrush(Colors.Red, Colors.Blue, 20.0) 

End If 

' Create a new Pen, if necessary. 

If pen Is Nothing Then 

pen = New Pen(brush, 2.0) 

End If 

' Draw linear gradient ellipses between 
' all the StylusPoints that have come in. 

Dim i As Integer 

for i = 0 To stylusPoints.Count - 1 

Dim pt As Point = CType(stylusPoints(i), Point) 

Dim V As Vector = Point.Subtract(prevPoint, pt) 

' Only draw if we are at least 4 units away 
' from the end of the last ellipse. Otherwise, 

' we're just redrawing and wasting cycles. 

If V. Length > 4 Then 

' Set the thickness of the stroke based 
' on how hard the user pressed. 

Dim radius As Double = stylusPoints(i).PressurePactor * 10.0 
drawingContext.DrawEllipse(brush, pen, pt, radius, radius) 
prevPoint = pt 
End If 
Next i 

End Sub 
End Class 


Implementing Custom Strokes 

Implement a class that derives from Stroke. This class is responsible for rendering StylusPoint data after it has been 
converted into a Stroke object. Override the DrawCore class to do the actual drawing. 

Your Stroke class can also store custom data by using the AddPropertyData method. This data is stored with the 
stroke data when persisted. 



The Stroke class can also perform hit testing. You can also implement your own hit testing algorithm by overriding 
the HitTest method in the current class. 

The following C# code demonstrates a custom Stroke class that renders StylusPoint data as a 3D stroke. 

using System; 

using System.Windows.Media; 
using System.Windows; 

using System.Windows.Input.StylusPlugIns; 
using System.Windows.Input; 
using System.Windows.Ink; 


Imports System.Windows.Media 
Imports System.Windows 

Imports System.Windows.Input.StylusPlugIns 
Imports System.Windows.Input 
Imports System.Windows.Ink 


// A class for rendering custom strokes 
class CustomStroke : Stroke 
{ 

Brush brush; 

Pen pen; 

public CustomStroke(StylusPointCollection stylusPoints) 

: base(stylusPoints) 

{ 

// Create the Brush and Pen used for drawing. 

brush = new LinearGradientBrush(Colors.Redj Colors.Blue, 20d); 

pen = new Pen(brush, 2d); 

} 

protected override void DrawCore(DrawingContext drawingContext, 

DrawingAttributes drawingAttributes) 

{ 

// Allocate memory to store the previous point to draw from. 

Point prevPoint = new Point(double.Negativeinfinity, 

double.Negativeinfinity); 

// Draw linear gradient ellipses between 

// all the StylusPoints in the Stroke. 

for (int i = 0; i < this.StylusPoints.Count; i++) 

{ 

Point pt = (Point)this.StylusPoints[i]; 

Vector V = Point.Subtract(prevPoint, pt); 

// Only draw if we are at least 4 units away 
// from the end of the last ellipse. Otherwise, 

// we're just redrawing and wasting cycles, 
if (v.Length > 4) 

{ 

// Set the thickness of the stroke 
// based on how hard the user pressed. 

double radius = this.StylusPoints[i].PressureFactor ♦ 10d; 
drawingContext.DrawEllipse(brush, pen, pt, radius, radius); 
prevPoint = pt; 

} 

} 

} 

} 



' A class for rendering custom strokes 
Class CustomStroke 
Inherits Stroke 
Private brush As Brush 
Private pen As Pen 

Public Sub New(ByVal stylusPoints As StylusPointCollection) 
MyBase.New(stylusPoints) 

' Create the Brush and Pen used for drawing. 

brush = New LinearGradientBrush(Colors.Redj Colors.Blue, 20.0) 
pen = New Pen(brushj 2.0) 

End Sub 


Protected Overrides Sub DrawCore(ByVal drawingContext As DrawingContext, _ 

ByVal drawingAttributes As DrawingAttributes) 

' Allocate memory to store the previous point to draw from. 

Dim prevPoint As New Point(Double.NegativeInfinityj Double.Negativeinfinity) 

' Draw linear gradient ellipses between 
' all the StylusPoints in the Stroke. 

Dim i As Integer 

For i = 0 To Me.StylusPoints.Count - 1 

Dim pt As Point = CType(Me.StylusPoints(i)j Point) 

Dim V As Vector = Point.Subtract(prevPointj pt) 

' Only draw if we are at least 4 units away 
' from the end of the last ellipse. Otherwise, 

' we're just redrawing and wasting cycles. 

If V. Length > 4 Then 

' Set the thickness of the stroke 
' based on how hard the user pressed. 

Dim radius As Double = Me.StylusPoints(i).PressureFactor * 10.0 
drawingContext.DrawEllipse(brush, pen, pt, radius, radius) 
prevPoint = pt 
End If 
Next i 

End Sub 
End Class 


Implementing a Custom InkCanvas 

The easiest way to use your customized DynamicRenderer and stroke is to implement a class that derives from 
InkCanvas and uses these classes. The InkCanvas has a DynamicRenderer property that specifies how the stroke is 
rendered when the user is drawing it. 

To custom render strokes on an InkCanvas do the following: 

• Create a class that derives from the InkCanvas. 

• Assign your customized DynamicRenderer to the InkCanvas.DynamicRenderer property. 

• Override the OnStrokeCollected method. In this method, remove the original stroke that was added to the 
InkCanvas. Then create a custom stroke, add it to the Strokes property, and call the base class with a new 
InkCanvasStrokeCollectedEventArgs that contains the custom stroke. 

The following C# code demonstrates a custom InkCanvas class that uses a customized DynamicRenderer and 
collects custom strokes. 



public class CustomRenderingInkCanvas : InkCanvas 

{ 

CustomDynamicRenderer customRendenen = new CustomDynamicRenderer()j 

public CustomRenderingInkCanvas() : base() 

{ 

// Use the custom dynamic rendenen on the 
// custom InkCanvas. 
this.DynamicRenderen = customRenderer; 

} 

protected override void OnStrokeCollected(InkCanvasStrokeCollectedEventArgs e) 

{ 

// Remove the original stroke and add a custom stroke, 
this.Strokes.Remove(e.Stroke); 

CustomStroke customStroke = new CustomStroke(e.Stroke.StylusPoints); 
this.Strokes.Add(customStroke); 

// Pass the custom stroke to base class' OnStrokeCollected method. 
InkCanvasStrokeCollectedEventArgs args = 

new InkCanvasStrokeCollectedEventArgs(customStroke); 
base.OnStrokeCollected(args); 

} 

} 


An InkCanvas can have more than one DynamicRenderer. You can add multiple DynamicRenderer objects to the 
InkCanvas by adding them to the StylusPlugIns property. 

Conclusion 

You can customize the appearance of ink by deriving your own DynamicRenderer, Stroke, and InkCanvas classes. 
Together, these classes ensure that the appearance of the stroke is consistent when the user draws the stroke and 
after it is collected. 

See also 


• Advanced Ink Handling 



Intercepting Input from the Stylus 
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The System.Windows.Input.StylusPlugIns architecture provides a mechanism for implementing low-level control 
over Stylus input and the creation of digital ink Stroke objects. The StylusPlugIn class provides a mechanism for 
you to implement custom behavior and apply it to the stream of data coming from the stylus device for the 
optimal performance. 

This topic contains the following subsections: 

• Architecture 

• Implementing Stylus Plug-ins 

• Adding Your Plug-in to an InkCanvas 

• Conclusion 

Architecture 

The StylusPlugIn is the evolution of the Stylusinput APIs, described in Accessing and Manipulating Pen Input. 

Each UlElement has a StylusPlugIns property that is a StylusPlugInCollection. You can add a StylusPlugIn to an 
element's StylusPlugIns property to manipulate StylusPoint data as it is generated. StylusPoint data consists of all 
the properties supported by the system digitizer, including the X and Y point data, as well as PressureFactor data. 

Your StylusPlugIn objects are inserted directly into the stream of data coming from the Stylus device when you add 
the StylusPlugIn to the StylusPlugIns property. The order in which plug-ins are added to the StylusPlugIns 
collection dictates the order in which they will receive StylusPoint data. For example, if you add a filter plug-in that 
restricts input to a particular region, and then add a plug-in that recognizes gestures as they are written, the plug¬ 
in that recognizes gestures will receive filtered StylusPoint data. 

Implementing Stylus Plug-ins 

To implement a plug-in, derive a class from StylusPlugIn. This class is applied o the stream of data as it comes in 
from the Stylus. In this class you can modify the values of the StylusPoint data. 

Caution 

If a StylusPlugIn throws or causes an exception, the application will close. You should thoroughly test controls that 
consume a StylusPlugIn and only use a control if you are certain the StylusPlugIn will not throw an exception. 

The following example demonstrates a plug-in that restricts the stylus input by modifying the X and Y values in the 
StylusPoint data as it comes in from the Stylus device. 

using System; 

using System.Windows.Media; 
using System.Windows; 

using System. Windows. Input .StylusPlugIns; 
using System.Windows.Input; 
using System.Windows.Ink; 





Imports System.Windows.Media 
Imports System.Windows 

Imports System.Windows.Input.StylusPlugIns 
Imports System.Windows.Input 
Imports System.Windows.Ink 


// A StylusPlugin that restricts the input area, 
class FilterPlugin : StylusPlugin 
{ 

protected override void OnStylusDown(RawStylusInput rawStylusInput) 

{ 

// Call the base class before modifying the data, 
base.OnStylusDown(rawStylusInput); 

// Restrict the stylus input. 

Filter(rawStylusInput); 

} 

protected override void OnStylusHove(RawStylusInput rawStylusInput) 

{ 

// Call the base class before modifying the data, 
base.OnStylusMove(rawStylusInput); 

// Restrict the stylus input. 

Filter(rawStylusInput); 

} 

protected override void OnStylusUp(RawStylusInput rawStylusInput) 

{ 

// Call the base class before modifying the data, 
base.OnStylusUp(rawStylusInput); 

// Restrict the stylus input 
Filter(rawStylusInput); 

} 

private void Filter(RawStylusInput rawStylusInput) 

{ 

// Get the StylusPoints that have come in. 

StylusPointCollection stylusPoints = rawStylusInput.GetStylusPoints() 

// Modify the (XjY) data to move the points 
// inside the acceptable input area^ if necessary, 
for (int i = 0; i < stylusPoints.Count; i++) 

{ 

StylusPoint sp = stylusPoints[i]; 
if (sp.X < 50) sp.X = 50; 
if (sp.X > 250) sp.X = 250; 
if (sp.Y < 50) sp.Y = 50; 
if (sp.Y > 250) sp.Y = 250; 
stylusPoints[i] = sp; 

} 

// Copy the modified StylusPoints back to the RawStylusInput. 
rawStylusInput.SetStylusPoints(stylusPoints); 

} 



' A StylusPlugin that restricts the input area. 

Class FilterPlugin 

Inherits StylusPlugin 

Protected Overrides Sub OnStylusDown(ByVal rawStylusInput As RawStylusInput) 
' Call the base class before modifying the data. 

MyBase.OnStylusDown(rawStylusInput) 

' Restrict the stylus input. 

Filter(rawStylusInput) 

End Sub 


Protected Overrides Sub OnStylusMove(ByVal rawStylusInput As RawStylusInput) 
' Call the base class before modifying the data. 

MyBase.OnStylusMove(rawStylusInput) 

' Restrict the stylus input. 

Filter(rawStylusInput) 

End Sub 


Protected Overrides Sub OnStylusUp(ByVal rawStylusInput As RawStylusInput) 
' Call the base class before modifying the data. 

MyBase.OnStylusUp(rawStylusInput) 

' Restrict the stylus input 
Filter(rawStylusInput) 

End Sub 


Private Sub Filter(By\/al rawStylusInput As RawStylusInput) 

' Get the StylusPoints that have come in. 

Dim StylusPoints As StylusPointCollection = rawStylusInput.GetStylusPoints() 

' Modify the (X^Y) data to move the points 
' inside the acceptable input area^ if necessary. 

Dim i As Integer 

For i = 0 To StylusPoints.Count - 1 

Dim sp As StylusPoint = stylusPoints(i) 

If sp.X < 50 Then 
sp.X = 50 
End If 

If sp.X > 250 Then 
sp.X = 250 
End If 

If sp.Y < 50 Then 
sp.Y = 50 
End If 

If sp.Y > 250 Then 
sp.Y = 250 
End If 

stylusPoints(i) = sp 
Next i 

' Copy the modified StylusPoints back to the RawStylusInput. 
rawStylusInput.SetStylusPoints(StylusPoints) 

End Sub 
End Class 


Adding Your Plug-in to an InkCanvas 



The easiest way to use your custom plug-in is to implement a class that derives from InkCanvas and add it to the 
StylusPlugIns property. 

The following example demonstrates a custom InkCanvas that filters the ink. 

public class FiltenlnkCanvas : InkCanvas 
{ 

FilterPlugin filter = new FilterPlugin(); 

public FilterInkCanvas() 

: base() 

{ 

this.StylusPlugIns.Add(filter); 

} 

} 

If you add a FiiterinkCanvas to your application and run it, you will notice that the ink isn't restricted to a region 
until after the user completes a stroke. This is because the InkCanvas has a DynamicRenderer property, which is a 
StylusPlugIn and is already a member of the StylusPlugIns collection. The custom StylusPlugIn you added to the 
StylusPlugIns collection receives the StylusPoint data after DynamicRenderer receives data. As a result, the 
StylusPoint data will not be filtered until after the user lifts the pen to end a stroke. To filter the ink as the user 
draws it, you must insert the FilterPlugin before the DynamicRenderer. 

The following C# code demonstrates a custom InkCanvas that filters the ink as it is drawn. 

public class DynamicallyFilteredInkCanvas : InkCanvas 
{ 

FilterPlugin filter = new FilterPlugin(); 

public DynamlcallyFilteredlnkCanvasO 
: base() 

{ 

int dynamicRenderIndex = 

this.StylusPlugIns.IndexOf(this.DynamicRenderer); 
this.StylusPlugIns.Insert(dynamicRenderIndex, filter); 

} 

} 


Conclusion 

By deriving your own StylusPlugIn classes and inserting them into StylusPlugInCollection collections, you can 
greatly enhance the behavior of your digital ink. You have access to the StylusPoint data as it is generated, giving 
you the opportunity to customize the Stylus input. Because you have such low-level access to the StylusPoint data, 
you can implement ink collection and rendering with optimal performance for your application. 

See also 

• Advanced Ink Handling 

• Accessing and Manipulating Pen Input 
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You can create a custom control that dynamically and statically renders ink. That is, render ink as a user draws a 
stroke, causing the ink to appear to "flow" from the tablet pen, and display ink after it is added to the control, 
either via the tablet pen, pasted from the Clipboard, or loaded from a file. To dynamically render ink, your control 
must use a DynamicRenderer. To statically render ink, you must override the stylus event methods 
(OnStylusDown, OnStylusMove, and OnStylusUp) to collect StylusPoint data, create strokes, and add them to an 
InkPresenter (which renders the ink on the control). 

This topic contains the following subsections: 

• How to; Collect Stylus Point Data and Create Ink Strokes 

• How to; Enable Your Control to Accept Input from the Mouse 

• Putting it together 

• Using Additional Plug-ins and DynamicRenderers 

• Conclusion 

How to: Collect Stylus Point Data and Create Ink Strokes 

To create a control that collects and manages ink strokes do the following: 

1. Derive a class from Control or one of the classes derived from Control, such as Label. 


using System; 

using System.Windows.Ink; 

using System.Windows.Input; 

using System.Windows.Input.StylusPlugIns; 

using System.Windows.Controls; 

using System.Windows; 


class InkControl : Label 
{ 


} 


2. Add an InkPresenter to the class and set the Content property to the new InkPresenter. 


InkPresenter ip; 

public InkControlO 
{ 

// Add an InkPresenter for drawing, 
ip = new InkPresenterO; 
this.Content = ip; 

} 


3. Attach the RootVisual of the DynamicRenderer to the InkPresenter by calling the AttachVisuals method, and 






add the DynamicRenderer to the StylusPlugIns collection. This allows the InkPresenter to display the ink as 
the stylus point data is collected by your control. 

public InkControlO 

{ 


// Add a dynamic Tenderer that 

// draws ink as it "flows" from the stylus. 

dr = new DynamicRenderer(); 

ip.AttachVisuals(dr.RootVisual, dr.DrawingAttributes); 
this.StylusPlugIns.Add(dr); 


4. Override the OnStylusDown method. In this method, capture the stylus with a call to Capture. By capturing 
the stylus, your control will to continue to receive StylusMove and StylusUp events even if the stylus leaves 
the control's boundaries. This is not strictly mandatory, but almost always desired for a good user 
experience. Create a new StylusPointCollection to gather StylusPoint data. Finally, add the initial set of 
StylusPoint data to the StylusPointCollection. 

protected override void OnStylusDown(StylusDownEventArgs e) 

{ 

// Capture the stylus so all stylus input is routed to this control. 

Stylus.Capture(this); 

// Allocate memory for the StylusPointsCollection and 

// add the StylusPoints that have come in so far. 

stylusPoints = new StylusPointCollection(); 

StylusPointCollection eventPoints = 

e.GetStylusPoints(this, stylusPoints.Description); 

stylusPoints.Add(eventPoints); 

} 


5. Override the OnStylusMove method and add the StylusPoint data to the StylusPointCollection object that 
you created earlier. 

protected override void OnStylusMove(StylusEventArgs e) 

{ 

if (stylusPoints == null) 

{ 

return; 

} 

// Add the StylusPoints that have come in since the 
// last call to OnStylusMove. 

StylusPointCollection newStylusPoints = 

e.GetStylusPoints(this, stylusPoints.Description); 
stylusPoints.Add(newStylusPoints); 


6. Override the OnStylusUp method and create a new Stroke with the StylusPointCollection data. Add the new 
Stroke you created to the Strokes collection of the InkPresenter and release stylus capture. 




protected override void OnStylusUp(StylusEventArgs e) 

{ 

if (stylusPoints == null) 

{ 

return; 

} 

// Add the StylusPoints that have come in since the 
// last call to OnStylusMove. 

StylusPointCollection newStylusPoints = 

e.GetStylusPolnts(this, stylusPoints.Description); 
stylusPoints.Add(newStylusPoints); 

// Create a new stroke from all the StylusPoints since OnStylusDown. 
Stroke stroke = new Stroke(stylusPoints); 

// Add the new stroke to the Strokes collection of the InkPresenter. 
ip.Strokes.Add(stroke); 

// Clear the StylusPointsCollection. 
stylusPoints = null; 

// Release stylus capture. 

Stylus.Capture(null); 


How to: Enable Your Control to Accept Input from the Mouse 

If you add the preceding control to your application, run it, and use the mouse as an input device, you will notice 
that the strokes are not persisted. To persist the strokes when the mouse is used as the input device do the 
following: 

1. Override the OnMouseLeftButtonDown and create a new StylusPointCollection Get the position of the 
mouse when the event occurred and create a StylusPoint using the point data and add the StylusPoint to the 
StylusPointCollection. 

protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e) 

{ 

base.OnMouseLeftButtonDown(e); 

// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

// Start collecting the points. 
stylusPoints = new StylusPointCollection(); 

Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 

} 


2. Override the OnMouseMove method. Get the position of the mouse when the event occurred and create a 
StylusPoint using the point data. Add the StylusPoint to the StylusPointCollection object that you created 
earlier. 




protected override void OnMouseMove(MouseEventArgs e) 

{ 

base.OnMouseMove(e); 

// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

// Don't collect points unless the left mouse button 
// is down. 

if (e.LeftButton == MouseButtonState.Released || 
stylusPoints == null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 


3. Override the OnMouseLeftButtonUp method. Create a new Stroke with the StylusPointCollection data, and 
add the new Stroke you created to the Strokes collection of the InkPresenter. 

protected override void OnMouseLeftButtonLlp(MouseButtonEventArgs e) 

{ 

base.OnMouseLeftButtonUp(e); 

// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

if (stylusPoints == null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 

// Create a stroke and add it to the InkPresenter. 

Stroke stroke = new Stroke(stylusPoints); 
stroke.DrawingAttributes = dr.DrawingAttributes; 
ip.Strokes.Add(stroke); 

stylusPoints = null; 

} 


Putting it together 


The following example is a custom control that collects ink when the user uses either the mouse or the pen. 




using System; 

using System.Windows.Ink; 

using System.Windows.Input; 

using System.Windows.Input.StylusPlugIns; 

using System.Windows.Controls; 

using System.Windows; 


// A control for managing ink input 
class InkControl : Label 
{ 

InkPresenter ip; 

DynamicRenderer dr; 

// The StylusPointsCollection that gathers points 
// before Stroke from is created. 

StylusPointCollection stylusPoints = null; 

public InkControlO 

{ 

// Add an InkPresenter for drawing, 
ip = new InkPresenter(); 
this.Content = ip; 

// Add a dynamic tenderer that 

// draws ink as it "flows" from the stylus. 

dr = new DynamicRenderer(); 

ip.AttachVisuals(dr.RootVisualj dr.DrawingAttributes); 
this.StylusPluglns.Add(dr); 

} 

static InkControlO 

{ 

// Allow ink to be drawn only within the bounds of the control. 

Type owner = typeof(InkControl); 

ClipToBoundsProperty.OverrideMetadata(owner, 
new FrameworkPropertyMetadata(true)); 

} 

protected override void OnStylusDown(StylusDownEventArgs e) 

{ 

// Capture the stylus so all stylus input is routed to this control. 
Stylus.Capture(this); 

// Allocate memory for the StylusPointsCollection and 
// add the StylusPoints that have come in so far. 
stylusPoints = new StylusPointCollection(); 

StylusPointCollection eventPoints = 

e.GetStylusPoints(this, stylusPoints.Description); 

stylusPoints.Add(eventPoints); 

} 

protected override void OnStylusMove(StylusEventArgs e) 

{ 

if (stylusPoints == null) 

{ 

return; 

} 

// Add the StylusPoints that have come in since the 
// last call to OnStylusMove. 

StylusPointCollection newStylusPoints = 

e.GetStylusPoints(this, stylusPoints.Description); 
stylusPoints.Add(newStylusPoints); 

} 





protected override void OnStylusUp(StylusEventArgs e) 

{ 

if (stylusPoints == null) 

{ 

return; 

} 

// Add the StylusPoints that have come in since the 
// last call to OnStylusMove. 

StylusPointCollection newStylusPoints = 

e.GetStylusPoints(this^ stylusPoints.Description); 
stylusPoints.Add(newStylusPoints); 

// Create a new stroke from all the StylusPoints since OnStylusDown 
Stroke stroke = new Stroke(stylusPoints); 

// Add the new stroke to the Strokes collection of the InkPresenter 
ip.Strokes.Add(stroke); 

// Clear the StylusPointsCollection. 
stylusPoints = null; 

// Release stylus capture. 

Stylus.Capture(null); 

} 

protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e) 

{ 


base.OnMouseLeftButtonDown(e); 

// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

// Start collecting the points. 
stylusPoints = new StylusPointCollection(); 
Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 


protected override void OnMouseMove(MouseEventArgs e) 

{ 


base.OnMouseMove(e); 

// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

// Don't collect points unless the left mouse button 
// is down. 

if (e.LeftButton == MouseButtonState.Released || 
stylusPoints == null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 


protected override void OnMouseLeftButtonUp(MouseButtonEventArgs e) 

{ 


base.OnMouseLeftButtonUp(e); 


// If a stylus generated this event, return, 
if (e.StylusDevice != null) 

{ 

return; 

} 

if (stylusPoints == null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 
stylusPoints.Add(new StylusPoint(pt.X, pt.Y)); 

// Create a stroke and add it to the InkPresenter. 
Stroke stroke = new Stroke(stylusPoints); 
stroke.DrawingAttrihutes = dr.DrawingAttrihutes; 
ip.Strokes.Add(stroke); 

stylusPoints = null; 

} 

} 


Using Additional Plug-ins and DynamicRenderers 

Like the InkCanvas, your custom control can have custom StylusPlugIn and additional DynamicRenderer objects. 
Add these to the StylusPlugIns collection. The order of the StylusPlugIn objects in the StylusPluglnCollection affects 
the appearance of the ink when it is rendered. Suppose you have a DynamicRenderer called dynamicRenderer and 
a custom StylusPlugIn called transiatePiugin that offsets the ink from the tablet pen. If transiatePiugin is the 
first StylusPlugIn in the StylusPluglnCollection, and dynamicRenderer is the second, the ink that "flows" will be 
offset as the user moves the pen. If dynamicRenderer is first, and transiatePiugin is Second, the ink will not be 
offset until the user lifts the pen. 

Conclusion 

You can create a control that collects and renders ink by overriding the stylus event methods. By creating your own 
control, deriving your own StylusPlugIn classes, and inserting them the into StylusPluglnCollection, you can 
implement virtually any behavior imaginable with digital ink. You have access to the StylusPoint data as it is 
generated, giving you the opportunity to customize Stylus input and render it on the screen as appropriate for 
your application. Because you have such low-level access to the StylusPoint data, you can implement ink collection 
and render it with optimal performance for your application. 

See also 

• Advanced Ink Handling 

• Accessing and Manipulating Pen Input 
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One of the benefits of ink on a Tablet PC is that it feels a lot like writing with a regular pen and paper. To 
accomplish this, the tablet pen collects input data at a much higher rate than a mouse does and renders the ink as 
the user writes. The application's user interface (Ul) thread is not sufficient for collecting pen data and rendering 
ink, because it can become blocked. To solve this, a WPF application uses two additional threads when a user 
writes ink. 

The following list describes the threads that take part in collecting and rendering digital ink: 

• Pen thread - the thread that takes input from the stylus. (In reality, this is a thread pool, but this topic refers 
to it as a pen thread.) 

• Application user interface thread - the thread that controls the user interface of the application. 

• Dynamic rendering thread - the thread that renders the ink while the user draws a stroke. The dynamic 
rendering thread is different than the thread that renders other Ul elements for the application, as 
mentioned in Window Presentation Foundation Threading Model. 

The inking model is the same whether the application uses the InkCanvas or a custom control similar to the one in 
Creating an Ink Input Control. Although this topic discusses threading in terms of the InkCanvas, the same 
concepts apply when you create a custom control. 


Threading Overview 

The following diagram illustrates the threading model when a user draws a stroke: 
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1. Actions occurring while the user draws the stroke 

a. When the user draws a stroke, the stylus points come in on the pen thread. Stylus plug-ins, including 
the DynamicRenderer, accept the stylus points on the pen thread and have the chance to modify 
them before the InkCanvas receives them. 

b. The DynamicRenderer renders the stylus points on the dynamic rendering thread. This happens at 
the same time as the previous step. 

c. The InkCanvas receives the stylus points on the Ul thread. 

2. Actions occurring after the user ends the stroke 

a. When the user finishes drawing the stroke, the InkCanvas creates a Stroke object and adds it to the 
InkPresenter, which statically renders it. 

b. The Ul thread alerts the DynamicRenderer that the stroke is statically rendered, so the 
DynamicRenderer removes its visual representation of the stroke. 










Ink collection and Stylus Plug-ins 

Each UlElement has a StylusPlugInCollection. The StylusPlugIn objects in the StylusPlugInCollection receive and can 
modify the stylus points on the pen thread. The StylusPlugIn objects receive the stylus points according to their 
order in the StylusPlugInCollection. 


The following diagram illustrates the hypothetical situation where the StylusPlugIns collection of a UlElement 
contains styiusPiugini , a DynamicRenderer, and styiusPiugin2 , in that order. 
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In the previous diagram, the following behavior takes place: 

1. StyiusPiugini modifies the values for X and y. 

2. DynamicRenderer receives the modified stylus points and renders them on the dynamic rendering thread. 

3. styiusPiugin2 receives the modified stylus points and further modifies the values for x and y. 

4. The application collects the stylus points, and, when the user finishes the stroke, statically renders the 
stroke. 

Suppose that styiusPiugini restricts the Stylus points to a rectangle and styiusPiugin2 translates the stylus 
points to the right. In the previous scenario, the DynamicRenderer receives the restricted stylus points, but not the 
translated stylus points. When the user draws the stroke, the stroke is rendered within the bounds of the rectangle, 
but the stroke doesn't appear to be translated until the user lifts the pen. 

Performing operations with a Stylus Plug-in on the UI thread 

Because accurate hit-testing cannot be performed on the pen thread, some elements might occasionally receive 
stylus input intended for other elements. If you need to make sure the input was routed correctly before 
performing an operation, subscribe to and perform the operation in the OnStylusDownProcessed, 
OnStylusMoveProcessed, or OnStylusUpProcessed method. These methods are invoked by the application thread 
after accurate hit-testing has been performed. To subscribe to these methods, call the NotifyWhenProcessed 
method in the method that occurs on the pen thread. 

The following diagram illustrates the relationship between the pen thread and UI thread with respect to the stylus 
events of a StylusPlugIn. 
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Rendering Ink 

As the user draws a stroke, DynamicRenderer renders the ink on a separate thread so the ink appears to "flow" 
from the pen even when the UI thread is busy. The DynamicRenderer builds a visual tree on the dynamic rendering 
thread as it collects stylus points. When the user finishes the stroke, the DynamicRenderer asks to be notified when 
the application does the next rendering pass. After the application completes the next rendering pass, the 
DynamicRenderer cleans up its visual tree. The following diagram illustrates this process. 
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1. The user begins the Stroke. 

a. The DynamicRenderer creates the visual tree. 

2. The user is drawing the stroke. 

a. The DynamicRenderer builds the visual tree. 

3. The user ends the stroke. 

a. The InkPresenter adds the stroke to its visual tree. 

b. The Media Integration Layer (MIL) statically renders the strokes. 

c. The DynamicRenderer cleans up the visuals. 
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By adding an IncrementalLassoHitTester to your custom control, you can enable your control so that a user can 
select ink with a lasso tool, similar to the way the InkCanvas selects ink with a lasso. 

This example assumes you are familiar with creating an ink-enabled custom control. To create a custom control that 
accepts ink input, see Creating an Ink Input Control. 

Example 

When the user draws a lasso, the IncrementalLassoHitTester predicts which strokes will be within the lasso path's 
boundaries after the user completes the lasso. Strokes that are determined to be within the lasso path's boundaries 
can be thought of as being selected. Selected strokes can also become unselected. For example, if the user reverses 
direction while drawing the lasso, the IncrementalLassoHitTester may unselect some strokes. 

The IncrementalLassoHitTester raises the SelectionChanged event, which enables your custom control to respond 
while the user is drawing the lasso. For example, you can change the appearance of strokes as the user selects and 
unselects them. 

Managing the Ink Mode 

It is helpful to the user if the lasso appears differently than the ink on your control. To accomplish this, your custom 
control must keep track of whether the user is writing or selecting ink. The easiest way to do this is to declare an 
enumeration with two values: one to indicate that the user is writing ink and one to indicate that the user is 
selecting ink. 

// Enum that keeps track of whether StrokeCollectionDemo is in ink mode 
// or select mode, 
public enum InkMode 
{ 

Inkj Select 

} 


' Enum that keeps track of whether StrokeCollectionDemo is in ink mode 
' or select mode. 

Public Enum InkMode 
Ink 

[Select] 

End Enum 'InkMode 


Next, add two DrawingAttributes to the class: one to use when the user writes ink, one to use when the user selects 
ink. In the constructor, initialize the DrawingAttributes and attach both AttributeChanged events to the same event 
handler. Then set the DrawingAttributes property of the DynamicRenderer to the ink DrawingAttributes. 

DrawingAttributes inkDA; 

DrawingAttributes selectDA; 






Private inkDA As DrawingAttributes 
Private selectDA As DrawingAttributes 


// In the constructor. 

// Selection drawing attributes use dark gray ink. 
selectDA = new DrawingAttributes(); 
selectDA.Color = Colors.DarkGray; 

// ink drawing attributes use default attributes 
inkDA = new DrawingAttributes(); 
inkDA.Width = 5; 
inkDA.Height = 5; 

inkDA.AttributeChanged += new PropertyDataChangedEventHandler(DrawingAttributesChanged); 
selectDA.AttributeChanged += new PropertyDataChangedEventHandler(DrawingAttributesChanged)j 


' In the constructor. 

' Selection drawing attributes use dark gray ink. 
selectDA = New DrawingAttributes() 
selectDA.Color = Colors.DarkGray 

' ink drawing attributes use default attributes 
inkDA = New DrawingAttributes() 
inkDA.Width = 5 
inkDA.Height = 5 

AddHandler inkDA.AttributeChanged^ _ 

AddressOf DrawingAttributesChanged 

AddHandler selectDA.AttributeChanged^ _ 

AddressOf DrawingAttributesChanged 


Add a property that exposes the selection mode. When the user changes the selection mode, set the 
DrawingAttributes property of the DynamicRenderer to the appropriate DrawingAttributes object and then reattach 
the RootVisual Property to the InkPresenter. 



// Property to indicate whether the user is inputting or 
// selecting ink. 
public InkMode Mode 
{ 

get 

{ 

return mode; 

} 

set 

{ 

mode = value; 

// Set the DrawingAttributes of the DynamicRenderer 
if (mode == InkMode.Ink) 

{ 

renderer.DrawingAttributes = inkDA; 

} 

else 

{ 

renderer.DrawingAttributes = selectDA; 

} 

// Reattach the visual of the DynamicRenderer to the InkPresenter. 
presenter .Detach\/isuals( renderer. RootVisual); 

presenter.Attach\/isuals(renderer.RootVisualj renderer.DrawingAttributes); 

} 

} 


' Property to indicate whether the user is inputting or 
' selecting ink. 

Public Property Mode() As InkMode 
Get 

Return Mode 
End Get 

Set(ByVal value As InkMode) 
modeState = value 

' Set the DrawingAttributes of the DynamicRenderer 
If modeState = InkMode.Ink Then 

renderer.DrawingAttributes = inkDA 

Else 

renderer.DrawingAttributes = selectDA 
End If 

' Reattach the visual of the DynamicRenderer to the InkPresenter. 
presenter .Detach\/isuals( renderer. RootVisual) 

presenter.AttachVisuals(renderer.RootVisualj renderer.DrawingAttributes) 
End Set 
End Property 


Expose the DrawingAttributes as properties so applications can determine the appearance of the ink strokes and 
selection strokes. 



// Property to allow the user to change the pen's DrawingAttributes. 
public DrawingAttributes InkDrawingAttributes 
{ 

get 

{ 

return inkDA; 

} 

} 

// Property to allow the user to change the Selector'newStroke DrawingAttributes. 
public DrawingAttributes SelectDrawingAttributes 
{ 

get 

{ 

return selectDA; 

} 

} 


' Property to allow the user to change the pen's DrawingAttributes. 

Public Readonly Property InkDrawingAttributes() As DrawingAttributes 
Get 

Return inkDA 
End Get 
End Property 

' Property to allow the user to change the Selector'newStroke DrawingAttributes. 
Public Readonly Property SelectDrawingAttributes() As DrawingAttributes 
Get 

Return selectDA 
End Get 
End Property 


When a property of a DrawingAttributes object changes, the RootVisual must be reattached to the InkPresenter. In 
the event handler for the AttributeChanged event, reattach the RootVisual to the InkPresenter. 

void DrawingAttributesChanged(object sender, PropertyDataChangedEventArgs e) 

{ 

// Reattach the visual of the DynamicRenderer to the InkPresenter 
// whenever the DrawingAttributes change, 
presenter.DetachVisuals(renderer.RootVisual); 

presenter.AttachVisuals(renderer.RootVisual, renderer.DrawingAttributes); 

} 


Private Sub DrawingAttributesChanged(ByVal sender As Object, _ 

ByVal e As PropertyDataChangedEventArgs) 

' Reattach the visual of the DynamicRenderer to the InkPresenter 
' whenever the DrawingAttributes change, 
presenter.DetachVisuals(renderer.RootVisual) 
presenter.AttachVisuals(renderer.RootVisual, _ 

renderer.DrawingAttributes) 

End Sub 


Using the IncrementalLassoHitTester 


Create and initialize a StrokeCollection that contains the selected strokes. 




// StylusPointCollection that collects the stylus points from the stylus events. 
StylusPointCollection stylusPoints; 


' StylusPointCollection that collects the stylus points from the stylus events. 
Private stylusPoints As StylusPointCollection 


When the user starts to draw a stroke, either ink or the lasso, unselect any selected strokes. Then, if the user is 
drawing a lasso, create an IncrementalLassoHitTester by calling GetIncrementalLassoHitTester, subscribe to the 
SelectionChanged event, and call AddPoints. This code can be a separate method and called from the 
OnStylusDown and OnMouseDown methods. 

private void InitializeHitTester(StylusPointCollection collectedPoints) 

{ 

// Deselect any selected strokes. 

foreach (Stroke selectedStroke in selectedStrokes) 

{ 

selectedStroke.DrawingAttributes.Color = inkDA.Colorj 

} 

selectedStrokes.Clear(); 

if (mode == InkMode.Select) 

{ 

// Remove the previously drawn lassOj if it exists, 
if (lassoPath != null) 

{ 

presenter.Strokes.Remove(lassoPath); 
lassoPath = null; 

} 

selectionTester = 

presenter.Stpokes.GetIncrementalLassoHitTester(80); 
selectionTester.SelectionChanged += 

new LassoSelectionChangedEventHandler(selectionTester_SelectionChanged); 
selectionTester.AddPoints(collectedPoints); 

} 

} 


Private Sub InitializeHitTester(ByVal collectedPoints As StylusPointCollection) 

' Deselect any selected strokes. 

Dim selectedStroke As Stroke 

For Each selectedStroke In selectedStrokes 

selectedStroke.DrawingAttributes.Color = inkDA.Color 
Next selectedStroke 
selectedStrokes.Clear() 

If modeState = InkMode.Select Then 

' Remove the previously drawn lasso, if it exists. 

If Not (lassoPath Is Nothing) Then 

presenter.Strokes.Remove(lassoPath) 
lassoPath = Nothing 
End If 

selectionTester = presenter.Strokes.GetIncrementalLassoHitTester(80) 

AddHandler selectionTester.SelectionChanged, AddressOf selectionTester_SelectionChanged 
selectionTester.AddPoints(collectedPoints) 

End If 

End Sub 




Add the stylus points to the IncrementalLassoHitTester while the user draws the lasso. Call the following method 
from the OnStylusMove, OnStylusUp, OnMouseMove, and OnMouseLeftButtonUp methods. 

private void AddPointsToHitTester(StylusPointCollection collectedPoints) 

{ 

if (mode == InkMode.Select && 
selectionTester != null && 
selectionTester.IsValid) 

{ 

// When the control is selecting strokes^ add the 
// stylus packetList to selectionTester. 
selectionTester.AddPoints(collectedPoints)j 

} 

} 


Private Sub AddPointsToHitTester(ByVal collectedPoints As StylusPointCollection) 

If modeState = InkMode.Select AndAlso _ 

Not selectionTester Is Nothing AndAlso _ 
selectionTester.IsValid Then 

' When the control is selecting strokes, add the 
' stylus packetList to selectionTester. 
selectionTester.AddPoints(collectedPoints) 

End If 

End Sub 


Handle the IncrementalLassoHitTester.SelectionChanged event to respond when the user selects and unselects 
strokes. The LassoSelectionChangedEventArgs class has the SelectedStrokes and DeselectedStrokes properties that 
get the strokes that were selected and unselected, respectively. 

void selectionTester_SelectionChanged(object sender, 

LassoSelectionChangedEventArgs args) 

{ 

// Change the color of all selected strokes to red. 
foreach (Stroke selectedStroke in args.SelectedStrokes) 

{ 

selectedStroke.DrawingAttributes.Color = Colors.Red; 

SelectedStrokes.Add(selectedStroke); 

} 

// Change the color of all unselected strokes to 
// their original color. 

foreach (Stroke unselectedStroke in args.DeselectedStrokes) 

{ 

unselectedStroke.DrawingAttributes.Color = inkDA.Color; 

SelectedStrokes.Remove(unselectedStroke); 

} 

} 




Private Sub selectionTester_SelectionChanged(ByVal sender As Object, _ 

ByVal args As LassoSelectionChangedEventArgs) 

' Change the color of all selected strokes to red. 

Dim selectedStroke As Stroke 

For Each selectedStroke In args.SelectedStrokes 

selectedStroke.DrawingAttributes.Color = Colors.Red 
selectedStrokes.Add(selectedStroke) 

Next selectedStroke 

' Change the color of all unselected strokes to 

' their original color. 

Dim unselectedStroke As Stroke 

For Each unselectedStroke In args.DeselectedStrokes 

unselectedStroke.DrawingAttributes.Color = inkDA.Color 
selectedStrokes.Remove(unselectedStroke) 

Next unselectedStroke 

End Sub 


When the user finishes drawing the lasso, unsubscribe fronn the SelectionChanged event and call EndHitTesting. 


if (mode == InkMode.Select && lassoPath == null) 

{ 

// Add the lasso to the InkPresenter and add the packetList 
// to selectionTester. 
lassoPath = newStroke; 

lassoPath.DrawingAttributes = selectDA.Clone()j 
presenter.Strokes.Add(lassoPath); 

selectionTester.SelectionChanged -= new LassoSelectionChangedEventHandler 
(selectionTester_SelectionChanged); 
selectionTester.EndHitTesting(); 

} 


If modeState = InkMode.Select AndAlso lassoPath Is Nothing Then 
' Add the lasso to the InkPresenter and add the packetList 
' to selectionTester. 
lassoPath = newStroke 

lassoPath.DrawingAttributes = selectDA.Clone() 
presenter.Strokes.Add(lassoPath) 

RemoveHandler selectionTester.SelectionChanged, _ 

AddressOf selectionTester_SelectionChanged 
selectionTester. EndElitTesting() 

End If 


Putting it All Together. 

The following example is a custom control that enables a user to select ink with a lasso. 

using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Media; 

using System.Windows.Input; 

using System.Windows.Input.StylusPlugIns; 

using System.Windows.Ink; 

// Enum that keeps track of whether StrokeCollectionDemo is in ink mode 
// or select mode, 
public enum InkMode 
{ 




iriKj beiecTi 

} 

// This control allows the user to input and select ink. When the 
// user selects inkj the lasso remains visible until they erase, or clip 
// the selected strokes, or clear the selection. When the control is 
// in selection mode, strokes that are selected turn red. 
public class InkSelector : Label 
{ 

InkMode mode; 

DrawingAttributes inkDA; 

DrawingAttributes selectDA; 

InkPresenter presenter; 

IncrementalLassoHitTester selectionTester; 

StrokeCollection selectedStrokes = new StrokeCollection(); 

// StylusPointCollection that collects the stylus points from the stylus events. 
StylusPointCollection stylusPoints; 

// Stroke that represents the lasso. 

Stroke lassoPath; 

DynamicRenderer renderer; 

public InkSelectorO 

{ 

mode = InkMode.Ink; 

// Use an InkPresenter to display the strokes on the custom control, 
presenter = new InkPresenter(); 
this.Content = presenter; 

// In the constructor. 

// Selection drawing attributes use dark gray ink. 
selectDA = new DrawingAttributes(); 
selectDA.Color = Colors.DarkGray; 

// ink drawing attributes use default attributes 
inkDA = new DrawingAttributes(); 
inkDA.Width = 5; 
inkDA.Height = 5; 

inkDA.AttributeChanged += new PropertyDataChangedEventHandler(DrawingAttributesChanged); 
selectDA.AttributeChanged += new PropertyDataChangedEventHandler(DrawingAttributesChanged); 

// Add a DynmaicRenderer to the control so ink appears 
// to "flow" from the tablet pen. 
renderer = new DynamicRenderer(); 
renderer.DrawingAttributes = inkDA; 
this.StylusPlugIns.Add(renderer); 
presenter .Attach\/isuals( renderer. RootVisual, 
renderer.DrawingAttributes); 

} 

static InkSelectorO 

{ 

// Allow ink to be drawn only within the bounds of the control. 

Type owner = typeof(InkSelector); 

ClipToBoundsProperty.OverrideHetadata(owner, 
new FrameworkPropertyMetadata(true)); 

} 

// Prepare to collect stylus packets. If Mode is set to Select, 

// get the IncrementalHitTester from the InkPresenter'newStroke 
// StrokeCollection and subscribe to its StrokeHitChanged event, 
protected override void OnStylusDown(StylusDownEventArgs e) 

{ 

base.OnStylusDown(e); 


Stylus.Capture(this); 


// Create a new StylusPointCollection using the StylusPointDescription 
// from the stylus points in the StylusDownEventArgs. 
stylusPoints = new StylusPointCollection(); 

StylusPointCollection eventPoints = e.GetStylusPoints(thiSj stylusPoints.Description); 
stylusPoints.Add(eventPoints); 

InitializeHitTester(eventPoints); 

} 

protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e) 

{ 

base.OnMouseLeftButtonDown(e); 

Mouse.Capture(this); 

if (e.StylusDevice != null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 

StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 
stylusPoints = new StylusPointCollection(); 
stylusPoints.Add(collectedPoints); 

InitializeHitTester(collectedPoints); 

} 

private void InitializeHitTester(StylusPointCollection collectedPoints) 

{ 

// Deselect any selected strokes. 

foreach (Stroke selectedStroke in selectedStrokes) 

{ 

selectedStroke.DrawingAttributes.Color = inkDA.Color; 

} 

selectedStrokes.Clear(); 

if (mode == InkMode.Select) 

{ 

// Remove the previously drawn lassOj if it exists, 
if (lassoPath != null) 

{ 

presenter.Strokes.Remove(lassoPath); 
lassoPath = null; 

} 

selectionTester = 

presenter.Strokes.GetIncrementaliassoHitTester(80); 
selectionTester.SelectionChanged += 

new LassoSelectionChangedEventHandler(selectionTester_SelectionChanged); 
selectionTester.AddPoints(collectedPoints); 

} 

} 

// Collect the stylus packets as the stylus moves, 
protected override void OnStylusMove(StylusEventArgs e) 

{ 

if (stylusPoints == null) 

{ 

return; 

} 


StylusPointCollection collectedPoints = e.GetStylusPoints(thiSj stylusPoints.Description) 


stylusPoints.Add(collectedPoints); 
AddPolntsToHitTestenCcollectedPoints); 


protected override void OnMouseMove(MouseEventArgs e) 

{ 

base.OnMouseMove(e); 

if (e.StylusDevice != null) 

{ 

return; 

} 

if (e.LeftButton == MouseButtonState.Released) 

{ 

return; 

} 

stylusPoints ??= new StylusPointCollection(); 

Point pt = e.GetPosition(this); 

StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 
stylusPoints.Add(collectedPoints); 

AddPointsToHitTester(collectedPoints); 

} 

private void AddPointsToHitTester(StylusPointCollection collectedPoints) 

{ 


if (mode == InkMode.Select && 
selectionTester != null && 
selectionTester.IsValid) 

{ 

// When the control is selecting strokes^ add the 
// stylus packetList to selectionTester. 
selectionTester.AddPoints(collectedPoints); 

} 

} 

// When the user lifts the stylus^ create a Stroke from the 
// collected stylus points and add it to the InkPresenter. 

// When the control is selecting strokes^ add the 
// point data to the IncrementalHitTester. 
protected override void OnStylusUp(StylusEventArgs e) 

{ 

stylusPoints ??= new StylusPointCollection(); 
StylusPointCollection collectedPoints = 

e.GetStylusPoints(thiSj stylusPoints.Description); 

stylusPoints.Add(collectedPoints); 

AddPointsToHitTester(collectedPoints); 

AddStrokeToPresenter(); 
stylusPoints = null; 

Stylus.Capture(null); 

} 

protected override void OnMouseLeftButtonLlp(MouseButtonEventArgs e) 

{ 


base.OnMouseLeftButtonUp(e); 
if (e.StylusDevice != null) return; 

if (stylusPoints == null) stylusPoints = new StylusPointCollection(); 


Point pt = e.GetPosition(this); 


StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 

stylusPoints.Add(collectedPoints); 

AddPointsToHitTesten(collectedPoints); 

AddStnokeToPresentenO; 

stylusPoints = null; 

Mouse.Capture(null); 

} 

private void AddStrokeToPresenter() 

{ 

Stroke newStroke = new Stroke(stylusPoints); 

if (mode == InkMode.Ink) 

{ 

// Add the stroke to the InkPresenter. 
newStroke.DrawingAttributes = inkDA.Clone(); 
presenter.Strokes.Add(newStroke); 

} 

if (mode == InkMode.Select && lassoPath == null) 

{ 

// Add the lasso to the InkPresenter and add the packetList 
// to selectionTester. 
lassoPath = newStroke; 

lassoPath.DrawingAttributes = selectDA.Clone(); 
presenter.Strokes.Add(lassoPath); 

selectionTester.SelectionChanged -= new LassoSelectionChangedEventHandler 
(selectionTester_SelectionChanged); 
selectionTester.EndHitTesting(); 

} 

} 

void selectionTester_SelectionChanged(object sender, 

LassoSelectionChangedEventArgs args) 

{ 

// Change the color of all selected strokes to red. 
foreach (Stroke selectedStroke in args.SelectedStrokes) 

{ 

selectedStroke.DrawingAttributes.Color = Colors.Red; 
selectedStrokes.Add(selectedStroke); 

} 

// Change the color of all unselected strokes to 
// their original color. 

foreach (Stroke unselectedStroke in args.DeselectedStrokes) 

{ 

unselectedStroke.DrawingAttributes.Color = inkDA.Color; 
selectedStrokes.Remove(unselectedStroke); 

} 


// Property to indicate whether the user is inputting or 
// selecting ink. 
public InkMode Mode 
{ 

get 

{ 

return mode; 

} 

set 

{ 

mode = value; 


// Set the DrawingAttributes of the DynamicRenderer 
if (mode == InkMode.Ink) 

{ 

renderen.DrawingAttributes = inkDA; 

} 

else 

{ 

renderer.DrawingAttributes = selectDA; 

} 

// Reattach the visual of the DynamicRenderer to the InkPresenter. 
presenter .Detach\/isuals( renderer. RootVisual); 

presenter.Attach\/isuals(renderer.RootVisual, renderer.DrawingAttributes) 

} 

} 

void DrawingAttributesChanged(object sender, PropertyDataChangedEventArgs e) 

{ 

// Reattach the visual of the DynamicRenderer to the InkPresenter 
// whenever the DrawingAttributes change, 
presenter .Detach\/isuals( renderer. RootVisual) j 

presenter.AttachVisuals(renderer.RootVisual, renderer.DrawingAttributes); 

} 

// Property to allow the user to change the pen's DrawingAttributes. 
public DrawingAttributes InkDrawingAttributes 
{ 

get 

{ 

return inkDA; 

} 

} 

// Property to allow the user to change the Selector'newStroke DrawingAttributes 
public DrawingAttributes SelectDrawingAttributes 
{ 

get 

{ 

return selectDA; 

} 

} 


Imports System.Windows 

Imports System.Windows.Controls 

Imports System.Windows.Media 

Imports System.Windows.Input 

Imports System.Windows.Input.StylusPlugIns 

Imports System.Windows.Ink 


' Enum that keeps track of whether StrokeCollectionDemo is in ink mode 
' or select mode. 

Public Enum InkMode 
Ink 

[Select] 

End Enum 'InkMode 

' This control allows the user to input and select ink. When the 
' user selects ink, the lasso remains visible until they erase, or clip 
' the selected strokes, or clear the selection. When the control is 
' in selection mode, strokes that are selected turn red. 

Public Class InkSelector 
Inherits Label 


Private modeState As InkMode 


Private inkDA As DrawingAttributes 
Private selectDA As DrawingAttributes 

Private presenter As InkPresenter 

Private selectionTester As IncrementalLassoHitTester 
Private selectedStrokes As New StrokeCollection() 

' StylusPointCollection that collects the stylus points from the stylus events. 
Private stylusPoints As StylusPointCollection 

' Stroke that represents the lasso. 

Private lassoPath As Stroke 

Private renderer As DynamicRenderer 


Public Sub New() 

modeState = InkMode.Ink 

' Use an InkPresenter to display the strokes on the custom control, 
presenter = New InkPresenter() 

Me.Content = presenter 

' In the constructor. 

' Selection drawing attributes use dark gray ink. 
selectDA = New DrawingAttributes() 
selectDA.Color = Colors.DarkGray 

' ink drawing attributes use default attributes 
inkDA = New DrawingAttributes() 
inkDA.Width = 5 
inkDA.Height = 5 

AddHandler inkDA.AttributeChangedj _ 

AddressOf DrawingAttributesChanged 

AddHandler selectDA.AttributeChangedj _ 

AddressOf DrawingAttributesChanged 

' Add a DynmaicRenderer to the control so ink appears 
' to "flow" from the tablet pen. 
renderer = New DynamicRenderer() 
renderer.DrawingAttributes = InkDA 
Me.StylusPlugIns.Add(renderer) 
presenter.Attach\/isuals(renderer.RootVisual, _ 
renderer.DrawingAttributes) 


End Sub 


Shared Sub New() 

' Allow ink to be drawn only within the bounds of the control. 
Dim owner As Type = GetType(InkSelector) 

ClipToBoundsProperty.OverrideMetadata(ownerj _ 

New FrameworkPropertyMetadata(True)) 


End Sub 

' Prepare to collect stylus packets. If Mode is set to Select, 

' get the IncrementalHitTester from the InkPresenter'newStroke 
' StrokeCollection and subscribe to its StrokeHitChanged event. 

Protected Overrides Sub OnStylusDown(ByVal e As StylusDownEventArgs) 
MyBase.OnStylusDown(e) 

Stylus.Capture(Me) 

' Create a new StylusPointCollection using the StylusPointDescription 
' from the stylus points in the StylusDownEventArgs. 
stvlusPoints = New StvlusPointCollectionO 


Dim eventPoints As StylusPointCollection = e.GetStylusPoints(Mej stylusPoints.Description) 


stylusPoints.Add(eventPoints) 

InitializeHitTester(eventPoints) 

End Sub 

Protected Overrides Sub OnMouseLeftButtonDown(ByVal e As MouseButtonEventArgs) 
MyBase.OnMouseLeftButtonDown(e) 

Mouse.Capture(Me) 

If Mot (e.StylusDevice Is Nothing) Then 
Return 
End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 
stylusPoints = New StylusPointCollection() 
stylusPoints.Add(collectedPoints) 

InitializeHitTester(collectedPoints) 

End Sub 


Private Sub InitializeHitTester(By\/al collectedPoints As StylusPointCollection) 

' Deselect any selected strokes. 

Dim selectedStroke As Stroke 

For Each selectedStroke In selectedStrokes 

selectedStroke.DrawingAttributes.Color = inkDA.Color 
Next selectedStroke 
selectedStrokes.Clear() 

If modeState = InkMode.Select Then 

' Remove the previously drawn lasso, if it exists. 

If Not (lassoPath Is Nothing) Then 

presenter.Strokes.Remove(lassoPath) 
lassoPath = Nothing 
End If 

selectionTester = presenter.Strokes.GetIncrementalLassoHitTester(80) 

AddElandler selectionTester.SelectionChanged, AddressOf selectionTester_SelectionChanged 
selectionTester.AddPoints(collectedPoints) 

End If 

End Sub 

' Collect the stylus packets as the stylus moves. 

Protected Overrides Sub OnStylusMove(ByVal e As StylusEventArgs) 

If stylusPoints Is Nothing Then 
Return 
End If 


Dim collectedPoints As StylusPointCollection = e.GetStylusPoints(Me, stylusPoints.Description) 
stylusPoints.Add(collectedPoints) 

AddPointsToElitTester( collectedPoints) 

End Sub 
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MyBase.OnMouseMove(e) 


If Not (e.StylusDevice Is Nothing) Then 
Return 
End If 

If e.LeftButton = MouseButtonState.Released Then 
Return 
End If 


If stylusPoints Is Nothing Then 

stylusPoints = New StylusPointCollection() 

End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 
stylusPoints.Add(collectedPoints) 

AddPointsToElitTester( collectedPoints) 

End Sub 


Private Sub AddPointsToElitTester(ByVal collectedPoints As StylusPointCollection) 

If modeState = InkMode.Select AndAlso _ 

Not selectionTester Is Nothing AndAlso _ 
selectionTester.IsValid Then 

' When the control is selecting strokes, add the 
' stylus packetList to selectionTester. 
selectionTester.AddPoints(collectedPoints) 

End If 

End Sub 

' When the user lifts the stylus, create a Stroke from the 
' collected stylus points and add it to the InkPresenter. 

' When the control is selecting strokes, add the 
' point data to the IncrementalElitTester. 

Protected Overrides Sub OnStylusLlp(ByVal e As StylusEventArgs) 

If stylusPoints Is Nothing Then 

stylusPoints = New StylusPointCollection() 

End If 

Dim collectedPoints As StylusPointCollection = _ 
e.GetStylusPoints(Me, stylusPoints.Description) 

stylusPoints.Add(collectedPoints) 

AddPointsToElitTester( collectedPoints) 

AddStrokeToPresenterO 

stylusPoints = Nothing 

Stylus.Capture(Nothing) 

End Sub 


Protected Overrides Sub OnMouseLeftButtonLlp(ByVal e As MouseButtonEventArgs) 
MyBase.OnMouseLeftButtonUp(e) 


If Not (e.StylusDevice Is Nothing) Then 
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End If 

If stylusPoints Is Nothing Then 

stylusPoints = New StylusPointCollection() 

End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 

stylusPoints.Add(collectedPoints) 

AddPointsToElitTesten( collectedPoints) 

AddStnokeToPresentenO 

stylusPoints = Nothing 

Mouse.Capture(Nothing) 

End Sub 


Private Sub AddStrokeToPresenter() 

Dim newStroke As New Stroke(stylusPoints) 

If modeState = InkMode.Ink Then 

' Add the stroke to the InkPresenter. 
newStroke.DrawingAttributes = inkDA.Clone() 
presenter.Strokes.Add(newStroke) 

End If 

If modeState = InkMode.Select AndAlso lassoPath Is Nothing Then 
' Add the lasso to the InkPresenter and add the packetList 
' to selectionTester. 
lassoPath = newStroke 

lassoPath.DrawingAttributes = selectDA.Clone() 
presenter.Strokes.Add(lassoPath) 

RemoveHandler selectionTester.SelectionChangedj _ 

AddressOf selectionTester_SelectionChanged 
selectionTester. EndElitTesting() 

End If 

End Sub 

Private Sub selectionTester_SelectionChanged(ByVal sender As Object, _ 

ByVal args As LassoSelectionChangedEventArgs) 

' Change the color of all selected strokes to red. 

Dim selectedStroke As Stroke 

for Each selectedStroke In args.SelectedStrokes 

selectedStroke.DrawingAttributes.Color = Colors.Red 
selectedStrokes.Add(selectedStroke) 

Next selectedStroke 

' Change the color of all unselected strokes to 
' their original color. 

Dim unselectedStroke As Stroke 

for Each unselectedStroke In args.DeselectedStrokes 

unselectedStroke.DrawingAttributes.Color = inkDA.Color 
selectedStrokes.Remove(unselectedStroke) 

Next unselectedStroke 

End Sub 

' Property to indicate whether the user is inputting or 

' selecting ink. 

Public Property Mode() As InkMode 
Get 

Return Mode 
End Get 


Set(By\/al value As InkMode) 
modeState = value 

' Set the DnawingAttributes of the DynamicRenderer 
If modeState = InkMode.Ink Then 

rendenen.DnawingAttributes = inkDA 

Else 

rendenen.DnawingAttributes = selectDA 
End If 

' Reattach the visual of the DynamicRenderer to the InkPresenter. 
presenter .Detach\/isuals(renderer. RootVisual) 

presenter.Attach\/isuals(renderer.RootVisualj renderer.DnawingAttributes) 
End Set 
End Property 

Private Sub DrawingAttributesChanged(ByVal sender As Object, _ 

ByVal e As PropertyDataChangedEventArgs) 

' Reattach the visual of the DynamicRenderer to the InkPresenter 
' whenever the DnawingAttributes change, 
presenter .Detach\/isuals( renderer. RootVisual) 
presenter.AttachVisuals(renderer.RootVisual, _ 

renderer.DnawingAttributes) 

End Sub 

' Property to allow the user to change the pen's DnawingAttributes. 

Public Readonly Property InkDrawingAttributes() As DnawingAttributes 
Get 

Return inkDA 
End Get 
End Property 

' Property to allow the user to change the Selector'newStroke DnawingAttributes. 
Public Readonly Property SelectDrawingAttributes() As DnawingAttributes 
Get 

Return selectDA 
End Get 
End Property 

End Class 


See also 

• IncrementalLassoHitTester 

• StrokeCol lection 

• StylusPointCollection 

• Creating an Ink Input Control 


How to: Add Custom Data to Ink Data 

4/28/2019 • 2 minutes to read ^ Edit Online 


You can add custom data to ink that will be saved when the ink is saved as ink serialized format (ISF). You can save 
the custom data to the DrawingAttributes, the StrokeCollection, or the Stroke. Being able to save custom data on 
three objects gives you the ability to decide the best place to save the data. All three classes use similar methods to 
store and access custom data. 

Only the following types can be saved as custom data: 

• Boolean 

• Boolean[] 

• Byte 

• Byte[] 

• Char 

• Char[] 

• DateTime 

• DateTime[] 

• Decimal 

• Decimal[] 

• Double 

• Double[] 

• Inti 6 

• Int16[] 

• Int32 

• Int32[] 

• Int64 

• Int64[] 

• Single 

• Single[] 

• String 

• UIntie 

• Ulnt16[] 

• Ulnt32 


Ulnt32[] 





• Ulnt64 


• Ulnt64[] 

Example 

The following example demonstrates how to add and retrieve custom data from a StrokeCollection. 

Guid timestamp = new Guid("12345678-9012-3456-7890-123456789012"); 

// Add a timestamp to the StrokeCollection. 
private void AddTimestampO 
{ 

inkCanvasl.Strokes.AddPropertyData(timestampj DateTime.Now); 

} 

// Get the timestamp of the StrokeCollection. 
private void GetTimestamp() 

{ 

if (inkCanvasl.Strokes.ContainsPropertyData(timestamp)) 

{ 

object date = inkCanvasl.Strokes.GetPropertyData(timestamp); 

if (date is DateTime) 

{ 

MessageBox.Show("This StrokeCollection's timestamp is " + 

((DateTime)date).ToString())j 

} 

} 

else 

{ 

MessageBox.Show( 

"The StrokeCollection does not have a timestamp."); 

} 

} 

The following example creates an application that displays an InkCanvas and two buttons. The button, 
switchAuthor , enables two pens to be used by two different authors. The button changePenCoiors changes the 
color of each stroke on the InkCanvas according to the author. The application defines two DrawingAttributes 
objects and adds a custom property to each one that indicates which author drew the Stroke. When the user clicks 
ChangePenCoiors , the application changes the appearance of the stroke according to the value of the custom 
property. 






<Window x:Class="Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
Title="Adding Custom Data to Ink" Height="500" Width="700" 

> 

<DockPanel Name="root"> 

<StackPanel Background="DarkSlateBlue"> 

<Button Name="switchAuthor" Click="switchAuthor_click" > 

Switch to student's pen 
</Button> 

<Button Name="changePenColors" Click="changeColor_click" > 
Change the color of the pen ink 
</Button> 

</StackPanel> 

<InkCanvas Name="inkCanvasl"> 

</InkCanvas> 

</DockPanel> 

</Window> 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Data; 

using System.Windows.Documents; 

using System.Windows.Media; 

using System.Windows.Media.Imaging; 

using System.Windows.Shapes; 

using System.Windows.Ink; 

III <summary> 

III Interaction logic for Windowl.xaml 
III </summary> 

public partial class Windowl : Window 

{ 

Quid authorGuid = new Guid("12345678-9012-3456-7890-123456789012") 

DrawingAttributes teachersDA = new DrawingAttributes(); 

DrawingAttributes studentsDA = new DrawingAttributes(); 

string teacher = "teacher"; 

string student = "student"; 

bool useStudentPen = false; 

public WindowlO 

{ 

InitializeComponentO; 

teachersDA.Color = Colors.Red; 
teachersDA.Width = 5; 
teachersDA.Height = 5; 

teachersDA.AddPropertyData(authorGuid, teacher); 

studentsDA.Color = Colors.Blue; 
studentsDA.Width = 5; 
studentsDA.Height = 5; 

studentsDA.AddPropertyData(authorGuid, student); 
inkCanvasl.DefaultDrawingAttributes = teachersDA; 

} 

// Switch between using the 'pen' DrawingAttributes and the 
// 'highlighter' DrawingAttributes. 

void switchAuthor_click(Object sender^ RoutedEventArgs e) 

{ 

useStudentPen = !useStudentPen; 


if (useStudentPen) 

{ 

switchAuthon.Content = "Use teacher's pen"; 
inkCanvasl.DefaultDrawingAttributes = studentsDA; 

} 

else 

{ 

switchAuthon.Content = "Use student's pen"; 
inkCanvasl.DefaultDrawingAttributes = teachersDA; 

} 

} 

// Change the color of the ink that on the InkCanvas that used the pen. 
void changeColor_click(Object sender^ RoutedEventArgs e) 

{ 

foreach (Stroke s in inkCanvasl.Strokes) 

{ 

if (s.DrawingAttributes.ContainsPropertyData(authorGuid)) 

{ 

object data = s.DrawingAttributes.GetPropertyData(authorGuid); 

if ((data is string) && ((string)data == teacher)) 

{ 

s.DrawingAttributes.Color = Colors.Black; 

} 

if ((data is string) && ((string)data == student)) 

{ 

s.DrawingAttributes.Color = Colors.Green; 

} 

} 

} 

} 

} 


How to: Erase Ink on a Custom Control 

3/5/2019 • 4 minutes to read ^ Edit Online 


The IncrementalStrokeHitTester determines whether the currently drawn stroke intersects another stroke. This is 
useful for creating a control that enables a user to erase parts of a stroke, the way a user can on an InkCanvas 
when the EditingMode is set to EraseByPoint. 

Example 

The following example creates a custom control that enables the user to erase parts of strokes. This example 
creates a control that contains ink when it is initialized. To create a control that collects ink, see Creating an Ink 
Input Control. 


using System.Windows; 
using System.Windows.Controls; 
using System.Windows.Ink; 
using System.Windows.Input; 
using System.Windows.Media; 
using System.10; 

// This control initializes with ink already on it and allows the 
// user to erase the ink with the tablet pen or mouse, 
public class InkEraser : Label 
{ 

IncrementalStrokeHitTester eraselester; 


InkPresenter presenter; 


string strokesString = 

@"ALwHAxdIEETLgIgERYQBGwIA]AFGhAEbAgAkAQUB0BkgMgkA9P8CAeki0kUzCQD4n" 
+ "wIBWiA6RTgIAP4DAAAAgH8RAACAPx83EQAAAAAAAPA/CiUHh/A6N4HR0AivFX8Vs" 
+ "IfsiuyLSaIeDSLwabiHm0GgLIDi+KZkACjsQh/A9t4IC5V]pf LhalxyxXIhZDncnh" 
+ "+6e7q0DwoERlPAw8EpGo]Agh61IKjCYXBYDA4DAIHF67KIHAAojB4fwMteBn+RKB" 
+ "lziaIfwWTeCwePqbM8WgIeeQCDQ0FRvcIAKNA+H8B8XgQHkUbjQTTnGuaZns314h" 
+ "/DWt4a0YKBBOA94D6HRCAiGnp5CS8LExMLBltOgYIAKUBOH8KnXhU71Mold+tcbi" 
+ "kChkqu2EtPYxp9bmYCH8HDHg4ZhMIwRyMHH+4]t8nleX8c0/D/AkYwx]GiHkkQgM" 
+ "Ch9CqcFhMDQCBwWAwuR2eAACmgdh/EpF41A6XMUfhMXgMHgVDxBFpRKpZII5EINA" 
+ "0A64M+34LwlCIoAh/B2x4PS4bQodAopEI5IIBki4waEx2Qy+dy+ayHgleEmmHH8c" 
+ "e3MZOCGw5TWd3CwsHAwMCgRAEAgElKwOHZKBApaGIfxezeL0uN02N8IzwaGEpNII" 
+ "ZxHnELyOj0GfyuU6FgmhplIgIfwYgeDHeaIlvjOtZgcHgHAYb9hUCgEFgsPmlxnM" 
+ "ZkYhsnY3gZeZh4uAgCgnSBI03v40AgwCmkgh/GrR41X4dGoR3L9EKra5HKY7IZ3C" 
+ "4fj/M06olSoU8kkehUbh8jkMdCH8I3XhAXhMCk83uNlmNyh0YiEumUwn2wMRxyHw" 
+ "2TzWmzeb02OzGKxMITwIhnrjzbb44zRhGEKRhCM4zrr6sQKXRWH8kuXkmPj0DiXC" 
+ "gc3bC9HZZgkKgUG4bLh3Yrw3HAYw2CAh/CiN4Tq7D0Zr4BB/AFtd0WW5P2hlWkzv" 
+ "14+YwqXf8d5fZ7ih51QKbB4LQrLAYDBIDABA4B04nAICApvIIfy4BeXA2DRSrQlL" 
+ "oHHsYQ/KMXlsvl8rn8Xkcdg+G9NVaUWimUDYk9Ah/BoF4M0YBCq2PYqk8dwLf7hD" 
+ "YNB3FLKBNqZTqNubWshl9VoMlreFYZYQEBGUsDAwKEjYuDQKBgICBgCAgI0Ag4nI" 
+ "80ACloSh/BF14Gf/I0t6FXfF8F4ToPCZzlPwP4+B+DHmQ0847rfDeCcG8eKh/EZV" 
+ "4i9eZt8A9nUF8VzxaUe5grl7YrPaHfpRK3Nx4yHmUujlvicwmMBEAjUVgKB61A="; 


public InkEraserO 

{ 

presenter = new InkPresenter(); 
this.Content = presenter; 


// Create a StrokeCollection the string and add it to 
StrokeCollectionConverter converter = 
new StrokeCollectionConverter(); 


if (converter.CanConvertFrom(typeof(String))) 





{ 

StrokeCollection newStrokes = 

converter.Conver'tFrom(strokesString) as StrokeCollection; 
presenter.Strokes.Clear(); 
presenter.Strokes.Add(newStrokes); 

} 

} 

protected override void OnStylusDown(StylusDownEventArgs e) 

{ 

base.OnStylusDown(e); 

StylusPointCollection points = e.GetStylusPoints(this); 
InitializeEraserHitTester(points); 

} 

protected override void OnMouseLeftButtonDown(MouseButtonEventArgs e) 

{ 

base.OnMouseLeftButtonDown(e); 

if (e.StylusDevice != null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 

StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 
InitializeEraserHitTester(collectedPoints); 

} 

// Prepare to collect stylus packets. Get the 
// IncrementalHitTester from the InkPresenter's 
// StrokeCollection and subscribe to its StrokeHitChanged event, 
private void InitializeEraserHitTester(StylusPointCollection points) 

{ 

EllipseStylusShape eraserTip = new EllipseStylusShape(3j 3j 0); 
eraseTester = 

presenter.Strokes.GetIncrementa1strokeHitTester(eraserTip); 
eraseTester.StrokeHit += new StrokeHitEventHandler(eraseTester_StrokeHit); 
eraseTester.AddPoints(points); 

} 

protected override void OnStylusMove(StylusEventArgs e) 

{ 

StylusPointCollection points = e.GetStylusPoints(this); 

AddPointsToEraserHitTester(points); 

} 

protected override void OnMouseMove(MouseEventArgs e) 

{ 

base.OnMouseMove(e); 

if (e.StylusDevice != null) 

{ 

return; 

} 

if (e.LeftButton == MouseButtonState.Released) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 


StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 


AddPointsToEraserHitTester'(collectedPoints); 

} 

// Collect the StylusPackets as the stylus moves. 

private void AddPointsToEraserHitTester(StylusPointCollection points) 

{ 

if (eraseTester.IsValid) 

{ 

eraseTester.AddPoints(points); 

} 

} 

// Unsubscribe from the StrokeHitChanged event when the 
// user lifts the stylus. 

protected override void OnStylusUp(StylusEventArgs e) 

{ 

StylusPointCollection points = e.GetStylusPoints(this)j 
StopEraseElitTesting( points); 

} 

protected override void OnMouseLeftButtonUp(MouseButtonEventArgs e) 

{ 

base.OnMouseLeftButtonUp(e); 

if (e.StylusDevice != null) 

{ 

return; 

} 

Point pt = e.GetPosition(this); 

StylusPointCollection collectedPoints = new StylusPointCollection(new Point[] { pt }); 
StopEraseElitTesting(collectedPoints); 

} 

private void StopEraseHitTesting(StylusPointCollection points) 

{ 

eraseTester.AddPoints(points); 
eraseTester.StrokeHit -= new 

StrokeHitEventHandler(eraseTester_StrokeElit); 
eraseTester. EndElitTesting(); 

} 

// When the stylus intersects a stroke, erase that part of 
// the stroke. When the stylus dissects a stoke, the 
// Stroke.Erase method returns a StrokeCollection that contains 
// the two new strokes, 
void eraseTester_StrokeElit(object sender, 

StrokeHitEventArgs args) 

{ 

StrokeCollection eraseResult = 
args. Get Point EraseResultsO; 

StrokeCollection strokesToReplace = new StrokeCollection(); 
strokesToReplace.Add(args.HitStroke); 

// Replace the old stroke with the new one. 
if (eraseResult.Count > 0) 

{ 

presenter.Strokes.Replace(strokesToReplace, eraseResult); 

} 

else 

{ 

presenter.Strokes.Remove(strokesToReplace); 

} 

} 

} 


Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Ink 
Imports System.Windows.Input 
Imports System.Windows.Media 
Imports System.10 

' This control initializes with ink already on it and allows the 
' user to erase the ink with the tablet pen or mouse. 

Public Class InkEraser 
Inherits Label 

Private eraseTester As IncrementalStrokeHitTester 


Private presenter As InkPresenter 


' The base-64 encoded string that contains ink data 
' in ink serialized format (ISF). 

Private strokesString As String = _ 

"ALwHAxdIEETLgIgERYQBGwIA]AFGhAEbAgAkAQUB0BkgMgkA9P8CAeki0kUzCQD4n" 
& "wIBWiA6RTgIAP4DAAAAgH8RAACAPx83EQAAAAAAAPA/CiUHh/A6N4HR0AivFX8Vs" 
& "IfsiuyLSaIeDSLwabiElm0GgLIDi+KZkACjsQh/A9t4IC5V]pfLhalxyxXIhTDncnh" 
& "+6e7q0DwoERlPAw8EpGoIAgh61IKjCYXBYDA4DAIHF67KIHAAojB4fwMteBn+RKB" 
& "lziaIfwWTeCwePqbM8WgIeeQCDQ0FRvcIAKNA+H8B8XgQHkUbjQTTnGuaZns314h" 
& "/DWt4a0YKBBOA94D6HRCAiGnp5CS8LExMLBltOgYIAKUBOH8KnXhU71Mold+tcbi" 
& "kChkqu2EtPYxp9bmYCH8HDHg4ZhMIwRyMHH+4]t8nleX8c0/D/AkYwxIGiHkkQgM" 
& "Ch9CqcFhMDQCBwWAwuR2eAACmgdh/EpF41A6XMUfhMXgMHgVDxBFpRKpZII5EINA" 
& "0A64M+D4LwlCIoAh/B2x4PS4bQodAopEI5I]Bki4waEx2Qy+dy+ayHgleEmmHH8c" 
& "e3MZOCGw5TWd3CwsHAwMCgRAEAgElKwOHZKBApaGIfxezeL0uN02N8IzwaGEpNII" 
& "ZxElnELyOj0GfyuU6FgmhplIgIfwYgeDHeaIlvjOtZgcElgEIAYb9hUCgEFgsPmlxnM" 
& "ZkYhsnY3gZeZh4uAgCgnSBI0]v40AgwCmkgh/GrR41X4dGoR3L9EKra5HKY7IZ3C" 
& "4fj/M06olSoU8kkehUbh8jkMdCH8I3XhAXhMCk83uNlmNyh0YiEumUwn2wMRxyHw" 
& "2TzWmzeb02OzGKxMITwIhnrjzbb44zRhGEKRhCM4zrr6sQKXRWH8kuXkmPj0DiXC" 
& "gc3bC9HZZgkKgUG4bLh3YrwIHAYw2CAh/CiN4Tq7D0Zr4BB/AFtd0WW5P2hlWkzv" 
& "14+YwqXf8d5fZ7ih51QKbB4LQrLAYDBIDABA4B04nAICApvIIfy4BeXA2DRSrQlL" 
& "oHHsYQ/KMXlsvl8rn8Xkcdg+G9NVaUWimUDYk9Ah/BoF4M0YBCq2PYqk8dwLf7hD" 
& "YNBIFLKBNqZTqNubWshl9VoMlreFYZYQEBGUsDAwKEjYuDQKBgICBgCAgI0Ag4nI" 
& "80ACloSh/BF14Gf/I0t6FXfF8F4ToPCZzlPwP4+B+DHmQ0847rfDeCcG8eKh/EZV" 
& "4i9eZt8A9nUF8VzxaUe5grl7YrPaHfpRK]Nx4yHmUujlvicwmMBEAjUVgKB61A=" 


Public Sub New() 

presenter = New InkPresenter() 
Me.Content = presenter 


' Create a StrokeCollection the string and add it to 
Dim converter As New StrokeCollectionConverter() 

If converter.CanConvertFrom(GetType(String)) Then 

Dim newStrokes As StrokeCollection = converter.ConvertFrom(strokesString) 

presenter.Strokes.Clear() 
presenter.Strokes.Add(newStrokes) 

End If 


End Sub 

Protected Overrides Sub OnStylusDown(ByVal e As StylusDownEventArgs) 
MyBase.OnStylusDown(e) 

Dim points As StylusPointCollection = e.GetStylusPoints(Me) 
InitializeEraserHitTester(points) 

End Sub 


Protected Overrides Sub OnMouseLeftButtonDown(ByVal e As MouseButtonEventArgs) 


MyBase.OnMouseLeftButtonDown(e) 


If Not (e.StylusDevice Is Nothing) Then 
Return 
End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 
InitializeEraserHitTester(collectedPoints) 

End Sub 

' Get the IncrementalHitTester from the InkPnesenter's 
' StrokeCollection and subscribe to its StrokeHitCbanged event. 

Private Sub InitializeEraserHitTester(ByVal points As StylusPointCollection) 

Dim eraserTip As New EllipseStylusShape(3j 0) 

eraseTester = presenter.Strokes.GetIncrementalStrokeHitTester(eraserTip) 
AddHandler eraseTester.StrokeHitj AddressOf eraseTester_StrokeHit 
eraseTester.AddPoints(points) 

End Sub 


Protected Overrides Sub OnStylusMove(ByVal e As StylusEventArgs) 
Dim points As StylusPointCollection = e.GetStylusPoints(Me) 

AddPointsToEraserHitTester(points) 

End Sub 


Protected Overrides Sub OnMouseMove(By\/al e As MouseEventArgs) 
MyBase.OnMouseMove(e) 

If Not (e.StylusDevice Is Nothing) Then 
Return 
End If 

If e.LeftButton = MouseButtonState.Released Then 
Return 
End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 
AddPointsToEraserHitTester(collectedPoints) 

End Sub 


' Collect the StylusPackets as the stylus moves. 

Private Sub AddPointsToEraserHitTester(ByVal points As StylusPointCollection) 


If eraseTester.IsValid Then 

eraseTester.AddPoints(points) 
End If 


End Sub 


' Unsubscribe from the StrokeHitCbanged event when the 
' user lifts the stylus. 

Protected Overrides Sub OnStylusUp(ByVal e As StylusEventArgs) 
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StopEraseHitTesting(points) 

End Sub 

Protected Overrides Sub OnMouseLeftButtonLlp(ByVal e As MouseButtonEventArgs) 

MyBase.OnMouseLeftButtonUp(e) 

If Not (e.StylusDevice Is Nothing) Then 
Return 
End If 

Dim pt As Point = e.GetPosition(Me) 

Dim collectedPoints As New StylusPointCollection(New Point() {pt}) 
StopEraseElitTesting(collectedPoints) 

End Sub 


Private Sub StopEraseElitTesting(By\/al points As StylusPointCollection) 
eraseTester.AddPoints(points) 

RemoveHandler eraseTester.StrokeHit, AddressOf eraseTester_StrokeHit 
eraseTester. EndElitTesting() 

End Sub 

' When the stylus intersects a stroke^ erase that part of 
' the stroke. When the stylus dissects a stoke, the 
' Stroke.Erase method returns a StrokeCollection that contains 
' the two new strokes. 

Private Sub eraseTester_StrokeHit(By\/al sender As Object, ByVal args As StrokeElitEventArgs) 

Dim eraseResult As StrokeCollection = args.GetPointEraseResults() 

Dim strokesToReplace As New StrokeCollection() 
strokesToReplace.Add(args.HitStroke) 

' Replace the old stroke with the new one. 

If eraseResult.Count > 0 Then 

presenter.Strokes.Replace(strokesToReplace, eraseResult) 

Else 

presenter.Strokes.Remove(strokesToReplace) 

End If 

End Sub 


End Class 


How To: Recognize Application Gestures 
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The following example demonstrates how to erase ink when a user makes a ScratchOut gesture on an InkCanvas. 
This example assumes an InkCanvas, called inkcanvasi , is declared in the XAML file. 

Example 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Ink; 

using System.Collections.ObjectModel; 

public partial class Windowl : Window 

{ 

public WindowlO 

{ 

InitializeComponent(); 

if (inkCanvasl.IsGestureRecognizerAvailable) 

{ 

inkCanvasl.EditingMode = InkCanvasEditingMode.InkAndGesture; 

inkCanvasl.Gesture += new InkCanvasGestureEventHandler(inkCanvasl_Gesture); 

inkCanvasl.SetEnabledGestures( 

new ApplicationGesture[] { ApplicationGesture.ScratcbOut }); 

} 

} 

void inkCanvasl_Gesture(object sender, InkCanvasGestureEventArgs e) 

{ 

ReadOnlyCollection<GestureRecognitionResult> gestureResults = 
e.GetGestureRecognitionResultsO; 

// Check the first recognition result for a gesture, 
if ((gestureResults[0].RecognitionConfidence == 

RecognitionConfidence.Strong) && 

(gestureResults[0].ApplicationGesture == 

ApplicationGesture.ScratcbOut)) 

{ 

StrokeCollection hitStrokes = inkCanvasl.Strokes.HitTest( 

e.Strokes.GetBoundsO, 10); 

if (hitStrokes.Count > 0) 

{ 

inkCanvasl.Strokes.Remove(hitStrokes); 

} 

} 

} 

} 






Imports System.Windows 

Imports System.Windows.Controls 

Imports System.Windows.Ink 

Imports System.Collections.ObjectModel 

Class Windowl 

Inherits Window 

Public Sub IMew() 

InitializeComponent() 

If inkCanvasl.IsGestureRecognizerAvailable Then 

inkCanvasl.EditingMode = InkCanvasEditingMode.InkAndGesture 
AddHandler inkCanvasl.Gesture, AddressOf inkCanvasl_Gesture 

inkCanvasl.SetEnabledGestures(New ApplicationGesture() {ApplicationGesture.ScratchOut}) 
End If 

End Sub 

Private Sub inkCanvasl_Gesture(ByVal sender As Object, ByVal e As InkCanvasGestureEventArgs) 

Dim gestureResults As ReadOnlyCollection(Of GestureRecognitionResult) = _ 
e.GetGestureRecognitionResultsO 

' Check the first recognition result for a gesture. 

If gestureResults(0).RecognitionConfidence = _ 

RecognitionConfidence.Strong AndAlso _ 
gestureResults(0).ApplicationGesture = _ 

ApplicationGesture.ScratchOut Then 

Dim hitStrokes As StrokeCollection = _ 

inkCanvasl. Strokes. ElitTest (e. Strokes. Get Bounds (), 10) 

If hitStrokes.Count > 0 Then 

inkCanvasl.Strokes.Remove(hitStrokes) 

End If 
End If 

End Sub 
End Class 


See also 

• ApplicationGesture 

• InkCanvas 

• Gesture 



How to: Drag and Drop Ink 
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Example 

The following example creates an application that enables the user to drag selected strokes from one InkCanvas to 
the other. 


<Window x:Class="Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
Title="Inl<DragDropSample" Height="500" Width="700" 

> 

<Grld> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto"/> 

<RowDefinition Height="*"/> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition/> 

<ColumnDefinition/> 

</Grid.ColumnDefinitions> 

<InkCanvas Name="icl" AllowDrop="True" 

Grid.Column="0" Grid.Row="0" 

Margin="10j10,10j10" Background="AliceBlue" 

PreviewMouseDown="InkCanvas_PreviewMouseDown" 

Drop="InkCanvas_Drop"/> 

<InkCanvas Name="ic2" AllowDrop="True" 

Grid.Column="l" Grid.Row="0" 

Margin="10,10^10^10" Background="Beige" 

PreviewMouseDown="InkCanvas_PreviewMouseDown" 

Drop="InkCanvas_Drop"/> 

<CheckBox Grid.Row="l" 

Checked="switchToSelect" Unchecked="switchToInk"> 

Select Mode 
</CheckBox> 

</Grid> 

</Window> 


using System; 
using System.10; 
using System.Windows; 
using System.Windows.Ink; 
using System.Windows.Controls; 
using System.Windows.Data; 
using System.Windows.Input; 
using System.Windows.Media; 

public partial class Windowl : Window 

{ 


public WindowlO 

{ 

InitializeComponent(); 

} 
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{ 


InkCanvas ic = (InkCanvas)sender'; 


Point pt = e.GetPosition(ic); 

// If the user is moving selected strokes, prepare the strokes to be 
// moved to another InkCanvas. 
if (ic.HitTestSelection(pt) == 

InkCanvasSelectionHitResult.Selection) 

{ 

StrokeCollection selectedStrokes = ic.GetSelectedStrokes()j 
StrokeCollection strokesToMove = selectedStrokes.Clone()j 

// Remove the offset of the selected strokes so they 
// are positioned when the strokes are dropped. 

Rect inkBounds = strokesToMove.GetBounds()j 
TranslateStrokes(strokesToMove, -inkBounds.X, -inkBounds.Y); 

// Perform drag and drop. 

MemoryStream ms = new MemoryStream(); 

StrokesToMove.Save(ms); 

DataObject dataObject = new DataObject( 

StrokeCollection.InkSerializedFormat, ms); 

DragDropEffects effects = 

DragDrop.DoDragDrop(ic, dataObject, 

DragDropEffects.Move); 

if ((effects & DragDropEffects.Move) == 

DragDropEffects.Move) 

{ 

// Remove the selected strokes 
// from the current InkCanvas. 
ic.Strokes.Remove(selectedStrokes); 

} 

} 

} 

void InkCanvas_Drop(object sender, DragEventArgs e) 

{ 

// Get the strokes that were moved. 

InkCanvas ic = (InkCanvas)sender; 

MemoryStream ms = (MemoryStream)e.Data.GetData( 

StrokeCollection.InkSerializedEormat); 

ms.Position = 0; 

StrokeCollection strokes = new StrokeCollection(ms); 

// Translate the strokes to the position at which 
// they were dropped. 

Point pt = e.GetPosition(ic); 

TranslateStrokes(strokes, pt.X, pt.Y); 

// Add the strokes to the InkCanvas and keep them selected, 
ic.Strokes.Add(strokes); 
ic. Select(strokes); 

} 

// Elelper method that translates the specified strokes, 
void TranslateStrokes(StrokeCollection strokes, 
double X, double y) 

{ 

Matrix mat = new Matrix(); 
mat.Translate(x, y); 
strokes.Transform(mat, false); 


void switchToSelect(object sender, RoutedEventArgs e) 

{ 
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ic2.EditingMode = InkCanvasEdltingMode.Select; 

} 

void switchToInk(object sender, RoutedEventArgs e) 

{ 

icl.EditingMode = InkCanvasEdltingMode.Ink; 
ic2.EditingMode = InkCanvasEdltingMode.Ink; 

} 

} 


Imports System.10 
Imports System.Windows 
Imports System.Windows.Ink 
Imports System.Windows.Controls 
Imports System.Windows.Data 
Imports System.Windows.Input 
Imports System.Windows.Media 

Class Windowl 

Inherits Window 

Public Sub New() 

InitializeComponent() 

End Sub 

Private Sub InkCanvas_PreviewMouseDown(ByVal sender As Object, _ 

ByVal e As MouseButtonEventArgs) 

Dim ic As InkCanvas = CType(sender, InkCanvas) 

Dim pt As Point = e.GetPosition(ic) 

' If the user is moving selected strokes, prepare the strokes to be 
' moved to another InkCanvas. 

If ic.HitTestSelection(pt) = InkCanvasSelectionHitResult.Selection Then 

Dim selectedStrokes As StrokeCollection = _ 

ic .GetSelectedStrokesO 

Dim strokesToMove As StrokeCollection = _ 

selectedStrokes.Clone() 

' Remove the offset of the selected strokes so they 
' are positioned when the strokes are dropped. 

Dim inkBounds As Rect = strokesToMove.GetBounds() 
TranslateStrokes(strokesToMove, -inkBounds.X, -inkBounds.Y) 

' Perform drag and drop. 

Dim ms As New MemoryStream() 

StrokesToMove.Save(ms) 

Dim dataObject As New DataObject _ 

(StrokeCollection.InkSerializedFormat, ms) 

Dim effects As DragDropEffects = _ 

DragDrop.DoDragDrop(ic, dataObject, DragDropEffects.Move) 

If (effects And DragDropEffects.Move) = DragDropEffects.Move Then 

' Remove the selected strokes from the current InkCanvas. 
ic.Strokes.Remove(selectedStrokes) 

End If 
End If 


End Sub 


Private Sub InkCanvas_Drop(ByVal sender As Object, _ 

ByVal e As DragEventArgs) 

' Get the strokes that were moved. 

Dim ic As InkCanvas = CType(sender, InkCanvas) 

Dim ms As MemoryStream = CType(e.Data.GetData( _ 

StrokeCollection.InkSerializedFormat), _ 

MemoryStream) 

ms.Position = 0 

Dim strokes As New StrokeCollection(ms) 

' Translate the strokes to the position at which 
' they were dropped. 

Dim pt As Point = e.GetPosition(ic) 
TranslateStrokes(strokes, pt.X, pt.Y) 

' Add the strokes to the InkCanvas and keep them selected, 
ic.Strokes.Add(strokes) 
ic.Select(strokes) 

End Sub 

’ Helper method that translates the specified strokes. 

Sub TranslateStrokes(ByVal strokes As StrokeCollection, _ 
ByVal X As Double, ByVal y As Double) 

Dim mat As New Matrix() 
mat.Translate(x, y) 
strokes.Transform(mat, False) 

End Sub 


Private Sub switchToSelect(ByVal sender As Object, 
ByVal e As RoutedEventArgs) 

icl.EditingMode = InkCanvasEditingMode.Select 
ic2.EditingMode = InkCanvasEditingMode.Select 

End Sub 


Private Sub switchToInk(ByVal sender As Object, 
ByVal e As RoutedEventArgs) 

icl.EditingMode = InkCanvasEditingMode.Ink 
ic2.EditingMode = InkCanvasEditingMode.Ink 

End Sub 


End Class 


How to: Data Bind to an InkCanvas 
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Example 

The following example demonstrates how to bind the Strokes property of an InkCanvas to another InkCanvas. 

<InkCanvas Background="LightGray" 

Canvas.Top="0" Canvas.Left="0" 

Height="400" Width="200" Name="ic"/> 

<!-- Bind the Strokes of the second InkCavas to the first InkCanvas 
and mirror the strokes along the Y axis.--> 

<InkCanvas Background="LightBlue" 

Canvas.Top="0" Canvas.Left="200" 

Helght="400" Width="200" 

Strokes="{Binding ElementName=iCj Path=Strokes}"> 

<InkCanvas.LayoutTransform> 

<ScaleTransform ScaleX="-l" ScaleY="l" /> 

</InkCanvas.LayoutTransform> 

</InkCanvas> 


The following example demonstrates how to bind the DefaultDrawingAttributes property to a data source. 

<Canvas.Resources> 

<!--Deflne an array containing some DrawingAttributes.--> 

<x:Array x:Key="MyDrawingAttributes" x:Type="{x:Type DrawingAttributes}"> 

<DrawingAttributes Color="Black" FitToCurve="true" Width="3" Height="3"/> 

<DrawingAttributes Color="Blue" FitToCurve="false" Width="5" Height="5"/> 

<DrawingAttributes Color="Red" FitToCurve="true" Width="7" Height="7"/> 

</x:Array> 

<!--Create a DataTemplate to display the DrawingAttributes shown above--> 

<DataTemplate DataType="{x:Type DrawingAttributes}" > 
cBorder Width="80" Height="{Binding Path=Height}"> 

<Border.Background > 

<SolidColorBrush Color="{Binding Path=Color}"/> 

</Border.Background> 

</Border> 

</DataTemplate> 

</Canvas.Resources> 


<!--Bind the InkCavas' DefaultDrawingAtributes to 
a ListboXj called IbDrawingAttributes.--> 

<InkCanvas IMame="inkCanvasl" Background="LightGreen" 

Canvas.Top="400" Canvas.Left="0" 

Helght="400" Width="400" 

DefaultDrawingAttrlbutes="{Binding 

ElementName=lbDrawingAttributeSj Path=SelectedItem}" 

> 

</InkCanvas> 

<!--Use the array^ MyDrawingAttributeSj to populate a ListBox--> 

<ListBox Name="IbDrawingAttributes" 

Canvas.Top="400" Canvas.Left="450" 

Height="100" Width="100" 

ItemsSource="{StaticResource MyDrawingAttributes}" /> 






The following example declares two InkCanvas objects in XAML and establishes data binding between them and 
other data sources. The first InkCanvas, called ic , is bound to two data sources. The EditingMode and 
DefaultDrawingAttributes properties on ic are bound to ListBox objects, which are in turn bound to arrays 
defined in the XAML. The EditingMode, DefaultDrawingAttributes, and Strokes properties of the second InkCanvas 
are bound to the first InkCanvas, ic . 

<Canvas> 

<Canvas. Resour'ces> 

<!--Define an array containing the InkEditingMode Values.--> 

<x:Array x:Key="MyEditingHodes" x:Type="{x:Type InkCanvasEditingMode}"> 

<x:Static Member="InkCanvasEditingMode.Ink"/> 

<x:Static Member="InkCanvasEditingMode.Select"/> 

<x:Static Member="InkCanvasEditingMode.EraseByPoint"/> 

<x:Static Member="InkCanvasEditingMode.EraseByStroke"/> 

</x:Array> 

<!--Define an array containing some DrawingAttributes.--> 

<x:Array x:Key="MyDrawingAttributes" 

x:Type="{x:Type DrawingAttributes}"> 

<DrawingAttributes Color="Black" EitToCurve="true" 

Width="3" Height="3"/> 

<DrawingAttributes Color="Blue" EitToCurve="false" 

Width="5" Height="5"/> 

<DrawingAttributes Color="Red" FitToCurve="true" 

Width="7" Height="7"/> 

</x:Array> 

<!--Create a DataTemplate to display the 
DrawingAttributes shown above--> 

<DataTemplate DataType="{x:Type DrawingAttributes}" > 

<Border Width="80" Height="{Binding Path=Height}"> 

<Border.Background > 

<SolidColorBrush Color="{Binding Path=Color}"/> 

</Border.Background> 

</Border> 

</DataTemplate> 

</Canvas.Resources> 

<!--Bind the first InkCavas' DefaultDrawingAtributes to a 

ListboXj called IbDrawingAttributeSj and its EditingMode to 
a ListBox called IbEditingMode.--> 

<InkCanvas Name="ic" Background="LightGray" 

Canvas.Top="0" Canvas.Left="0" 

Height="400" Width="200" 

DefaultDrawingAttributes="{Binding 

ElementName=lbDrawingAttributes, Path=SelectedItem}" 

EditingMode= 

"{Binding ElementName=lbEditingMode, Path=SelectedItem}" 

> 

</InkCanvas> 

<!--Bind the Strokes, DefaultDrawingAtributes, and, EditingMode properties of 
the second InkCavas the first InkCanvas.--> 

<InkCanvas Background="LightBlue" 

Canvas.Top="0" Canvas.Left="200" 

Height="400" Width="200" 

Strokes="{Binding ElementName=ic, Path=Strokes}" 

DefaultDrawingAttributes="{Binding 

ElementName=ic, Path=DefaultDrawingAttributes}" 

EditingMode="{Binding ElementName=ic, Path=EditingMode}"> 

<InkCanvas.LayoutTransform> 

<ScaleTransform ScaleX="-l" ScaleY="l" /> 

</InkCanvas.LayoutTransform> 


</InkCanvas> 




<!--Llse the anray^ MyEditingModeSj to populate a ListBox--> 
<ListBox IMame="lbEditingMode" 

Canvas.Top="0" Canvas.Left="450" 

Height="100" Width="100" 

ItemsSounce="{StatlcResource MyEditingModes}" /> 

<!--Use the anray^ MyDrawingAttributeSj to populate a ListBox--> 
<ListBox Name="lbDrawingAttnibutes" 

Canvas.Top="150" Canvas.Left="450" 

Height="100" Width="100" 

ItemsSounce="{StaticResource MyDnawingAttnibutes}" /> 

</Canvas> 


How to: Analyze Ink with Analysis Hints 
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An System.Windows.Ink.AnalysisHintNode provides a hint for the System.Windows.Ink.InkAnalyzer to which it is 
attached. The hint applies to the area specified by the System.Windows.lnk.ContextNode.Location%2A property of 
the System.Windows.Ink.AnalysisHintNode and provides extra context to the ink analyzer to improve recognition 
accuracy. The System.Windows.Ink.InkAnalyzer applies this context information when analyzing ink obtained from 
within the hint's area. 

Example 

The following example is an application that uses multiple System.Windows.Ink.AnalysisHintNode objects on a 
form that accepts ink input. The application uses the System.Windows.lnk.AnalysisHintNode.Factoid%2A property 
to provide context information for each entry on the form. The application uses background analysis to analyze the 
ink and clears the form of all ink five seconds after the user stops adding ink. 

<Window x:Class="For'mAnalyzer" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

Title="FormAnalyzer" 

SizeToContent="WidthAndHeight" 

> 

cStackPanel Orientation="Vertical") 

<InkCanvas Name="xaml_writingCanvas" Height="500" Width="840" 

StrokeCollected="RestartAnalysis" > 

<Grid> 

<Grid.Resources) 

<Style TargetType="{x:Type Label}") 

<Setter Property="FontSize" Value="20"/) 

<Setter Property="FontFamily" Value="Arial"/) 

</Style) 

<Style TargetType="{x:Type TextBlock}") 

cSetter Property="FontSize" Value="18"/) 

<Setter Property="VerticalAlignment" Value="Center"/) 

</Style) 

</Grid.Resources) 

<Grid.ColumnDefinitions) 

<ColumnDefinition Width="100")</ColumnDefinition) 

<ColumnDefinition Width="160")</ColumnDefinition) 

<ColumnDefinition Width="160")</ColumnDefinition) 

<ColumnDefinition Width="100")</ColumnDefinition) 

<ColumnDefinition Width="160")</ColumnDefinition) 

<ColumnDefinition Width="160")</ColumnDefinition) 

</Grid.ColumnDefinitions) 

<Grid.RowDefinitions) 

<RowDefinition Height="100")</RowDefinition) 

<RowDefinition Height="100")</RowDefinition) 

<RowDefinition Height=" 100"x/RowDefinition) 

<RowDefinition Height=" 100"x/RowDefinition) 

<RowDefinition Height="100")</RowDefinition) 

</Grid.RowDefinitions) 

<Label Grid.Row="0" Grid.Column="0")Title</Label) 

<Label Grid.Row="l" Grid.Column="0")Director</Label) 

<Label Grid.Row="2" Grid.Column="0")Starring</Label) 

<Label Grid.Row="3" Grid.Column="0")Rating</Label) 




<Label Grid.Row="3" Gr'id.Column="3">Year</Label> 
<Label Grid.Row="4" Grid.Column="0">Genre</Label> 


<TextBlock Name="xaml_blockTitle" 
Grid.Row="0" Gr'id.Column="l" 

Grid.ColumnSpan="5"/> 

<TextBlock IMame="xaml_blockDirector" 

Grld.Row="l" Grid.Column="l" 

Grid.ColumnSpan="5"/> 

<TextBlock IMame="xaml_blockStarring" 
Grid.Row="2" Grid.Column="l" 

Grid.ColumnSpan="5"/> 

<TextBlock Name="xaml_blockRating" 
Grid.Row="3" Grid.Column="l" 

Grid.ColumnSpan="2"/> 

<TextBlock Name="xaml_blockYear" 
Grid.Row="3" Grid.Column="4" 

Grid.ColumnSpan="2"/> 

<TextBlock IMame="xaml_blockGenre" 
Grid.Row="4" Grid.Column="l" 

Grid.ColumnSpan="5"/> 


<Line Grid.Row="0" Grid.Column="0" Grid.ColumnSpan="6" 
StrokeThickness="2" Stroke="Black" 

X1="0" Yl="100" X2="840" Y2="100" /> 

<Line Grid.Row="l" Grld.Column="0" Grid.ColumnSpan="6" 
StrokeThickness="2" Stroke="Black" 


X1="0" Yl="100" X2="840" Y2="100" /> 

<Line Grid.Row="2" Grid.Column="0" Grid.ColumnSpan="6" 
StrokeThickness="2" Stroke="Black" 

X1="0" Yl="100" X2="840" Y2="100" /> 

<Line Grid.Row="3" Grid.Column="0" Grid.ColumnSpan="6" 
StrokeThickness="2" Stroke="Black" 

X1="0" Yl="100" X2="840" Y2="100" /> 

<Line Grid.Row="3" Grid.Column="0" Grid.ColumnSpan="6" 
StrokeThickness="2" Stroke="Black" 

Xl="420" Y1="0" X2="420" Y2="100" /> 

</Grid> 

</InkCanvas> 

</StackPanel> 

</Window> 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Ink; 

using System.Windows.Threading; 

public partial class FormAnalyzer : Window 

{ 

private InkAnalyzer analyzer; 

private AnalysisHintNode hintNodelitle; 
private AnalysisHintNode hintNodeDirector; 
private AnalysisHintNode hintNodeStarring; 
private AnalysisHintNode hintNodeRating; 
private AnalysisHintNode hintNodeYear; 
private AnalysisHintNode hintNodeGenre; 

// Timer that raises an event to 
// clear the InkCanvas. 

private DispatcherTimer strokeRemovalTimer; 

private const int CLEAR_STROKES_DELAY = 5; 

public FormAnalyzer() 

{ 


InitializeComponent(); 

} 

protected override void OnContentRendered(EventArgs e) 

{ 

base.OnContentRendered(e); 

// Initialize the Analyzer, 
analyzer = new InkAnalyzer(); 
analyzer.ResultsUpdated += 

new ResultsUpdatedEventHandler(analyzer_ResultsLlpdated); 

// Add analysis hints for each form area. 

// Use the absolute Width and Height of the Grid's 
// RowDefinition and ColumnDefinition properties defined in XAMLj 
// to calculate the bounds of the AnalysisHintNode objects. 
hintNodeTitle = analyzer.CreateAnalysisHint( 

new Rect(100j <d, IVd, 100)); 
hintNodeDirector = analyzer.CreateAnalysisHint( 

new Rect(100, 100, 740, 100)); 
hintNodeStarring = analyzer.CreateAnalysisHint( 

new Rect(100, 200, 740, 100)); 
hintNodeRating = analyzer.CreateAnalysisHint( 

new Rect(100, 300, 320, 100)); 
hintNodeYear = analyzer.CreateAnalysisHint( 

new Rect(520, 300, 320, 100)); 
hintNodeGenre = analyzer.CreateAnalysisHint( 

new Rect(100, 400, 740, 100)); 

//Set the factoids on the hints. 
hintNodeTitle.Factoid = "(!IS_DEFAULT)''; 
hintNodeDirector.Factoid = "(!IS_PERSONALNAME_FULLNAME)"; 
hintNodeStarring.Factoid = "(!IS_PERSONALNAME_FULLNAME)"; 
hintNodeRating.Factoid = "(!IS_DEFAULT)"; 
hintNodeYear.Factoid = "(!IS_DATE_YEAR)"; 
hintNodeGenre.Factoid = "(!IS_DEFAULT)"; 

} 


III <summary> 

III InkCanvas.StrokeCollected event handler. Begins 

III ink analysis and starts the timer to clear the strokes. 

Ill If five seconds pass without a Stroke being added, 

III the strokes on the InkCanvas will be cleared. 

Ill </summary> 

III <par am name="sender">InkCanvas that raises the 
III StrokeCollected event.</param> 

III <param name="args">Contains the event data.</param> 
private void RestartAnalysis(object sender, 

InkCanvasStrokeCollectedEventArgs args) 


{ 


// If strokeRemovalTimer is enabled, stop it. 

if (strokeRemovalTimer != null && strokeRemovalTimer.IsEnabled) 

{ 

StrokeRemovalTimer.Stop(); 

} 

// Restart the timer to clear the strokes in five seconds 
StrokeRemovalTimer = new DispatcherTimer( 

TimeSpan.FromSeconds(CLEAR_STROKES_DELAY), 
DispatcherPriority.Normal, 

ClearCanvas, 

Dispatcher.CurrentDispatcher); 

// Add the new stroke to the InkAnalyzer and 
// begin background analysis, 
analyzer.AddStroke(args.Stroke); 
analyzer. BackgroundAnalyzeO; 


} 


Ill <summary> 

III Analyzer.ResultsUpdated event handler. 

Ill </summary> 

III <param name="sender">InkAnalyzer that raises the 
III event.</param> 

III <param name="e">Event data</param> 

III <remarks>This method checks each AnalysisHint for 
III analyzed ink and then populated the TextBlock that 
III corresponds to the area on the form.</remarks> 

void analyzer_ResultsUpdated(object sender^ ResultsUpdatedEventArgs e) 

{ 

string recoText; 

recoText = hintNodeTitle.GetRecognizedStringO j 
if (recoText != "") xaml_blockTitle.Text = recoText; 

recoText = hintNodeDirector.GetRecognizedStringO; 
if (recoText != "") xaml_blockDirector.Text = recoText; 

recoText = hintNodeStarring.GetRecognizedStringO; 
if (recoText != "") xaml_blockStarring.Text = recoText; 

recoText = hintNodeRating.GetRecognizedString(); 
if (recoText != "") xaml_blockRating.Text = recoText; 

recoText = hintNodeYear.GetRecognizedStringO; 
if (recoText != "") xaml_blockYear.Text = recoText; 

recoText = hintNodeGenre.GetRecognizedStringO; 
if (recoText != "") xaml_blockGenre.Text = recoText; 

} 

//Clear the canvas, but leave the current strokes in the analyzer, 
private void ClearCanvas(object sender, EventArgs args) 

{ 

strokeRemovalTimer.Stop(); 
xaml_writingCanvas.Strokes.Clear(); 

} 

} 


Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Ink 
Imports System.Windows.Threading 


Class FormAnalyzer 
Inherits Window 

Private analyzer As InkAnalyzer 

Private hintNodeTitle As AnalysisElintNode 
Private hintNodeDirector As AnalysisHintNode 
Private hintNodeStarring As AnalysisHintNode 
Private hintNodeRating As AnalysisHintNode 
Private hintNodeYear As AnalysisHintNode 
Private hintNodeGenre As AnalysisHintNode 

' Timer that raises an event to 
' clear the InkCanvas. 

Private strokeRemovalTimer As DispatcherTimer 
Private Const CLEAR_STROKES_DELAY As Integer = 5 


Public Sub IMew() 


InitializeComponent() 

End Sub 

Protected Overrides Sub OnContentRendered(ByVal e As EventArgs) 

MyBase.OnContentRendered(e) 

' Initialize the Analyzer, 
analyzer = New InkAnalyzer() 

AddElandler analyzer.ResultsUpdated, AddressOf analyzer_ResultsUpdated 

' Add analysis hints for each form area. 

' Use the absolute Width and Eleight of the Grid's 
' RowDefinition and ColumnDefinition properties defined in XAML, 

' to calculate the bounds of the AnalysisHintNode objects. 
hintNodeTitle = analyzer.CreateAnalysisHint(New Rect(100j 0, 740j 100)) 
hintNodeDirector = analyzer.CreateAnalysisElint(New Rect(100j 100j 740, 100)) 
hintNodeStarring = analyzer.CreateAnalysisElint(New Rect(100j 200j 740, 100)) 
hintNodeRating = analyzer.CreateAnalysisElint(New Rect(100j 300j 320, 100)) 
hintNodeYear = analyzer.CreateAnalysisElint(New Rect(520, 300, 320, 100)) 
hintNodeGenre = analyzer.CreateAnalysisHint(New Rect(100, 400, 740, 100)) 

'Set the factoids on the hints. 
hintNodeTitle.Factoid = "(!IS_DEFAULT)" 
hintNodeDirector.Factoid = "(!IS_PERSONALNAME_FULLNAME)" 
hintNodeStarring.Factoid = "(!IS_PERSONALNAME_FULLNAME)" 
hintNodeRating.Factoid = "(!IS_DEFAULT)" 
hintNodeYear.Factoid = "(!IS_DATE_YEAR)" 
hintNodeGenre.Factoid = "(!IS_DEFAULT)" 

End Sub 

' InkCanvas.StrokeCollected event handler. Begins 
' ink analysis and starts the timer to clear the strokes. 

' If five seconds pass without a Stroke being added, 

' the strokes on the InkCanvas will be cleared. 

' <param name="sender">InkCanvas that raises the 
' StrokeCollected event.</param> 

' <param name="args">Contains the event data.</param> 

Private Sub RestartAnalysis(By\/al sender As Object, ByVal args As InkCanvasStrokeCollectedEventArgs) 
' If strokeRemovalTimer is enabled, stop it. 

If Not (strokeRemovalTimer Is Nothing) AndAlso strokeRemovalTimer.IsEnabled Then 
StrokeRemovalTimer.Stop() 

End If 

' Restart the timer to clear the strokes in five seconds 
StrokeRemovalTimer = New DispatcherTimer( _ 

TimeSpan.FromSeconds(CLEAR_STROKES_DELAY), 

DispatcherPriority.Normal, _ 

AddressOf ClearCanvas, _ 

System.Windows.Threading.Dispatcher.CurrentDispatcher) 

' Add the new stroke to the InkAnalyzer and 
' begin background analysis. 
analyzer.AddStroke(args.Stroke) 
analyzer. BackgroundAnalyzeO 

End Sub 

' Analyzer.ResultsUpdated event handler. 

' <param name="sender">InkAnalyzer that raises the 
' event.</param> 

' <param name="e">Event data</param> 

' <remarks>This method checks each AnalysisHint for 
' analyzed ink and then populated the TextBlock that 
' corresponds to the area on the form.</remarks> 




Private Sub analyzer_ResultsUpdated(By\/al sender As Object^ ByVal e As ResultsUpdatedEventArgs) 
Dim recoText As String 

recoText = hintNodeTitle.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blocl<Title.Text = recoText 
End If 

recoText = hintNodeDirector.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blockDirector.Text = recoText 
End If 

recoText = hintNodeStarring.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blocl<Starring.Text = recoText 
End If 

recoText = hintNodeRating.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blockRating.Text = recoText 
End If 

recoText = hintNodeYear.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blockYear.Text = recoText 
End If 

recoText = hintNodeGenre.GetRecognizedStringO 
If recoText <> "" Then 

xaml_blockGenre.Text = recoText 
End If 

End Sub 

'Clear the canvas^ but leave the current strokes in the analyzer. 

Private Sub ClearCanvas(By\/al sender As Object^ ByVal args As EventArgs) 

strokeRemovalTimer.StopO 

xaml_writingCanvas.Strokes.Clear() 

End Sub 
End Class 


How to: Rotate Ink 

3/5/2019 • 6 minutes to read ^ Edit Online 


Example 

The following example copies the ink from an InkCanvas to a Canvas that contains an InkPresenter. When the 
application copies the ink, it also rotates the ink 90 degrees clockwise. 

<Canvas> 

<InkCanvas Name="inkCanvasl" Background="LightBlue" 

Height="200" Width="200" 

Canvas.Top="20" Canvas.Left="20" /> 

<Borden Name="canvasl" Backgnound="LightGreen" 

Height="200" Width="200" ClipToBounds="True" 

Canvas.Top="20" Canvas.Left="240" > 

<InkPresenter Name="inkPresenterl"/> 

</Border> 

<Button Click="button_Click" 

Canvas.Top="240" Canvas.Left="170"> 

Copy and Rotate Strokes 
</Button> 

</Canvas> 


// Button.Click event handler that rotates the strokes 
// and copies them to a Canvas. 

private void button_Click(object sender^ RoutedEventArgs e) 

{ 

StrokeCollection copiedStrokes = inkCanvasl.Strokes.Clone(); 

Matrix rotatingMatrix = new Matrix(); 

double canvasLeft = Canvas.GetLeft(inkCanvasl)j 

double canvasTop = Canvas.GetTop(inkCanvasl); 

Point rotatePoint = new Point(canvasl.Width / 2, canvasl.Height / 2)j 

rotatingMatrix.RotateAt(90, rotatePoint.X, rotatePoint.Y); 
copiedStrokes.Transform(rotatingMatrix, false); 
inkPresenterl.Strokes = copiedStrokes; 


Example 

The following example is a custom Adorner that rotates the strokes on an InkPresenter. 

using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Controls.Primitives; 

using System.Windows.Documents; 

using System.Windows.Input; 

using System.Windows.Media; 

using System.Windows.Shapes; 

using System.Windows.Ink; 

public class RotatingStrokesAdorner : Adorner 

{ 

// The Thumb to drag to rotate the strokes. 

Thumb rotateHandle; 





// The surrounding boarder. 

Path outline; 

VisualCollection visualChildren; 

// The center of the strokes. 

Point center; 
double lastAngle; 

RotateTransform rotation; 

const int HANDLEMARGIN = 10; 

// The bounds of the Strokes; 

Rect strokeBounds = Rect.Empty; 

public RotatingStrokesAdorner(LIIElement adornedElement) 
: base(adornedElement) 

{ 


visualChildren = new VisualCollection(this); 
rotateHandle = new Thumb(); 
rotateHandle.Cursor = Cursors.SizeNWSE; 
rotateHandle.Width = 20; 
rotateHandle.Height = 20; 
rotateHandle.Background = Brushes.Blue; 

rotateHandle.DragDelta += new DragDeltaEventHandler(rotateHandle_DragDelta); 
rotateHandle.DragCompleted += new DragCompletedEventHandler(rotateHandle_DragCompleted) 

outline = new Path(); 
outline.Stroke = Brushes.Blue; 
outline.StrokeThickness = 1; 

visualChildren.Add(outline); 
visualChildren.Add(rotateHandle); 

strokeBounds = AdornedStrokes.GetBounds(); 

} 

III <summary> 

III Draw the rotation handle and the outline of 
III the element. 

Ill </summary> 

III <param name="finalSize">The final area within the 
III parent that this element should use to arrange 
III itself and its children.</param> 

III <returns>The actual size used. </returns> 
protected override Size ArrangeOverride(Size finalSize) 

{ 

if (strokeBounds.IsEmpty) 

{ 

return finalSize; 

} 

center = new Point(strokeBounds.X + strokeBounds.Width / 2, 

strokeBounds.Y + strokeBounds.Height / 2); 

// The rectangle that determines the position of the Thumb. 

Rect handleRect = new Rect(strokeBounds.Xj 

strokeBounds.Y - (strokeBounds.Height / 2 + 

HANDLEMARGIN), 

strokeBounds.Width, strokeBounds.Height); 


if (rotation != null) 

{ 

1 


handleRect.Transform(rotation.Value); 


// Draws the thumb and the rectangle around the strokes. 

rotateHandle.Arrange(handleRect); 

outline.Data = new RectangleGeometry(strokeBounds)j 

outline.Arrange(new Rect(finalSize))j 

return finalSize; 

} 

III <summary> 

III Rotates the rectangle representing the 
III strokes' bounds as the user drags the 
/// Thumb. 

Ill </summary> 

void rotateHandle_DragDelta(object sender, DragDeltaEventArgs e) 

{ 

// Find the angle of which to rotate the shape. Use the right 
// triangle that uses the center and the mouse's position 
// as vertices for the hypotenuse. 

Point pos = Mouse.GetPosition(this); 

double deltaX = pos.X - center.X; 
double deltaY = pos.Y - center.Y; 

if (deltaY.Equals(0)) 

{ 

return; 

} 

double tan = deltaX / deltaY; 
double angle = Math.Atan(tan); 

// Convert to degrees, 
angle = angle * 180 / Math.PI; 

// If the mouse crosses the vertical center, 

// find the complementary angle, 
if (deltaY > 0) 

{ 

angle = 180 - Math.Abs(angle); 

} 

// Rotate left if the mouse moves left and right 
// if the mouse moves right, 
if (deltaX < 0) 

{ 

angle = -Hath.Abs(angle); 

} 

else 

{ 

angle = Math.Abs(angle); 

} 

if (Double.IsNaN(angle)) 

{ 

return; 

} 

// Apply the rotation to the strokes' outline. 

rotation = new RotateTransform(angle, center.X, center.Y); 

outline.RenderTransform = rotation; 

} 

III <summary> 

III Rotates the strokes to the same angle as outline. 

Ill </summary> 

void rotateHandle_DragCompleted(object sender. 
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if (rotation == null) 

{ 

return; 

} 

// Rotate the strokes to match the new angle. 
Matrix mat = new Matrix(); 

mat.RotateAt(rotation.Angle - lastAngle, center.X, 
AdornedStrokes.Transform(matj true); 

// Save the angle of the last rotation. 
lastAngle = rotation.Angle; 

// Redraw rotateHandle. 
this. InvalidateAr range 0; 


III <summary> 

III Gets the strokes of the adorned element 
III (in this casej an InkPresenter). 

Ill </summary> 

private StrokeCollection AdornedStrokes 

{ 

get 

{ 

return ((InkPresenter)AdornedElement).Strokes; 

} 

} 

// Override the VisualChildrenCount and 
// GetVisualChild properties to interface with 
// the adorner's visual collection, 
protected override int VisualChildrenCount 
{ 

get { return visualChildren.Count; } 

} 

protected override Visual GetVisualChild(int index) 

{ 

return visualChildren[index]; 

} 


Imports System.Windows 

Imports System.Windows.Controls 

Imports System.Windows.Controls.Primitives 

Imports System.Windows.Documents 

Imports System.Windows.Input 

Imports System.Windows.Media 

Imports System.Windows.Shapes 

Imports System.Windows.Ink 


Public Class RotatingStrokesAdorner 
Inherits Adorner 

' The Thumb to drag to rotate the strokes. 
Private rotateHandle As Thumb 

' The surrounding boarder. 

Private outline As Path 

Private visualChildren As VisualCollection 


' Thp rpirhpr n*f thp <;lTnk'p<;. 


center.Y) 


Private center As Point 
Private lastAngle As Double 

Private rotation As RotateTransform 

Private Const HANDLEMARGIN As Integer = 10 

' The bounds of the Strokes; 

Private strokeBounds As Rect = Rect.Empty 


Public Sub IMew(ByVal adornedElement As UIElement) 
MyBase.lMew(adornedElement) 

visualChildren = New VisualCollection(Me) 
rotateHandle = New Thumb() 
rotateHandle.Cursor = Cursors.SizeNWSE 
rotateHandle.Width = 20 
rotateHandle.Height = 20 
rotateHandle.Background = Brushes.Blue 

AddHandler rotateHandle.DragDeltaj _ 
AddressOf rotateHandle_DragDelta 
AddHandler rotateHandle.DragCompleted, _ 
AddressOf rotateHandle_DragCompleted 

outline = New Path() 
outline.Stroke = Brushes.Blue 
outline.StrokeThickness = 1 

visualChildren.Add(outline) 
visualChildren.Add(rotateHandle) 

strokeBounds = AdornedStrokes.GetBounds() 

End Sub 


''' <summary> 

''' Draw the rotation handle and the outline of 
' ' ' the element. 

''' </summary> 

' ' ' <param name="finalSize">The final area within the 
''' parent that this element should use to arrange 
itself and its children.</param> 

<returns>The actual size used. </returns> 

Protected Overrides Function ArrangeOverride(ByVal finalSize As Size) 
As Size 

If strokeBounds.IsEmpty Then 
Return finalSize 
End If 

center = New Point(strokeBounds.X + strokeBounds.Width / 2, _ 
strokeBounds.Y + strokeBounds.Height / 2) 

' The rectangle that determines the position of the Thumb. 

Dim handleRect As New Rect(strokeBounds.X, _ 

strokeBounds.Y - (strokeBounds.Height / 2 + _ 
HANDLEMARGIN), 

strokeBounds.Width, strokeBounds.Height) 

If Not (rotation Is Nothing) Then 

handleRect.Transform(rotation.Value) 

End If 

' Draws the thumb and the rectangle around the strokes. 
rotateHandle.Arrange(handleRect) 
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outline.Arrange(New Rect(finalSize)) 

Return finalSize 

End Function 'ArrangeOverride 


' ' ' <summary> 

''' Rotates the rectangle representing the 
strokes' bounds as the user drags the 
''' Thumb. 

''' </summary> 

Private Sub rotateHandle_DragDelta(ByVal sender As Object, _ 

ByVal e As DragDeltaEventArgs) 

'Find the angle of which to rotate the shape. Use the right 
'triangle that uses the center and the mouse's position 
'as vertices for the hypotenuse. 

Dim pos As Point = Mouse.GetPosition(Me) 

Dim deltaX As Double = pos.X - center.X 
Dim deltaY As Double = pos.Y - center.Y 

If deltaY.Equals(0) Then 
Return 
End If 

Dim tan As Double = deltaX / deltaY 
Dim angle As Double = Math.Atan(tan) 

' Convert to degrees, 
angle = angle * 180 / Math.PI 

' If the mouse crosses the vertical center, 

' find the complementary angle. 

If deltaY > 0 Then 

angle = 180 - Math.Abs(angle) 

End If 

' Rotate left if the mouse moves left and right 
' if the mouse moves right. 

If deltaX < 0 Then 

angle = -Math.Abs(angle) 

Else 

angle = Math.Abs(angle) 

End If 


If Double.IsNaN(angle) Then 
Return 
End If 


' Apply the rotation to the strokes' outline. 

rotation = New RotateTransform(angle, center.X, center.Y) 

outline.RenderTransform = rotation 

End Sub 


''' <summary> 

''' Rotates the strokes to the same angle as outline. 

' '' </summary> 

Private Sub rotateHandle_DragCompleted(ByVal sender As Object, _ 

ByVal e As DragCompletedEventArgs) 


If rotation Is Nothing Then 
Return 
End If 

' Rotate the strokes to match the new angle. 






Dim mat As New Matrlx() 

mat.RotateAt(rotation.Angle - lastAngle, center.X, center.Y) 
AdornedStrokes.Transform(matj True) 

' Save the angle of the last rotation. 
lastAngle = rotation.Angle 

' Redraw rotateHandle. 

Me. InvalidateArrangeO 

End Sub 

''' <summary> 

''' Gets the strokes of the adorned element 
(in this casej an InkPresenter). 

''' </summary> 

Private Readonly Property AdornedStrokes() As StrokeCollection 
Get 

Return CType(AdornedElementj InkPresenter).Strokes 
End Get 
End Property 

' Override the VisualChildrenCount and 
' GetVisualChild properties to interface with 
' the adorner's visual collection. 

Protected Overrides Readonly Property VisualChildrenCountO As Integer 
Get 

Return visualChildren.Count 
End Get 
End Property 

Protected Overrides Function Get\/isualChild(ByVal index As Integer) As Visual 
Return visualChildren(index) 

End Function 'GetVisualChild 
End Class 


The following example is a Extensible Application Markup Language (XAML) file that defines an InkPresenter and 
populates it with ink. The window_Loaded event handler adds the custom adorner to the InkPresenter. 


<Window x:Class="Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

Title="Rotating Strokes Adorner" Height="500" Width="500" 
Loaded="Window_Loaded" 

> 

<InkPresenter Name="inkPresenterl" > 

<InkPresenter.Strokes! 

ALMDAwRIEEUlBQE4GSAyCQD0/wIB6SI6RTMIAPifAgFaIDpFOAgA/gMAAACAfxEAAIA/ 
HwkRAAAAAAAA8D8KlwElh/CPd4SB4NA40icCjcGjcClcDj8Lh8DgUSkUmmU6nUmoUuk 
0ukUCQKVyehz+rzuly+bzORx+BReRQ+RTaRCH8]yXhPbgcPicPh8Pg8Oh0qklSoVGrV 
Oo0mi0Xi8rm9Xr9Dqc/p87pc/k8XicHicOjlCoVKtVmvlGqUaiUHlYg8el4akXK7m7T 
cS]gQgghEyym5zx6+PACk4dhPwg/fhCbxY8dp4p2tqnqxyvbP085zlXlaswhvCd94Tq 
55DRUGi4+Tk60Ln4KLko0ejo6ig5KTio0PCD9LlHmrzNxMRCCc3ec8+fe4AKQBmE/Cw 
9+FkPNvl0dkrYsWa+acp3Z8er0IT8]aX4S6+FbFilbHNvvPXNIbFqluxghKc5DkwrVF 
GEEIIlw5eLKYAKShuF+Dnr40a8HVHXNPFFFFho8VFkqsMRYuuv]xiF+F9r4Xx8HFiqs 
FNcirnweDw9+LvvvixdV0+GhONmlj3wjNOcSCEYTnfLy4oA 
</InkPresenter.Strokes! 

</InkPresenter! 

</Window! 




void Window_Loaded(object senden^ RoutedEventArgs e) 

{ 

// Add the rotating strokes adorner to the InkPresenter. 
adorneriayer = AdornerLayer.GetAdornerLayer(inkPresenterl)j 
adorner = new RotatingStrokesAdorner(inkPresenterl); 

adornerLayer.Add(adorner); 

} 


Private Suh Window_Loaded(By\/al sender As Ohjectj ByVal e As RoutedEventArgs) 

' Add the rotating strokes adorner to the InkPresenter. 
adorneriayer = adorneriayer.GetAdornerLayer(inkPresenterl) 
adorner = New RotatingStrokesAdorner(inkPresenterl) 

adornerLayer.Add(adorner) 

End Suh 



Disable the RealTimeStylus for WPF Applications 
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Windows Presentation Foundation (WPF) has built in support for processing Windows 7 touch input. The support 
comes through the tablet platform's real-time stylus input as OnStylusDown, OnStylusUp, and OnStylusMove 
events. Windows 7 also provides multi-touch input as Win32 WM_TOUCH window messages. These two APIs are 
mutually exclusive on the same HWND. Enabling touch input via the tablet platform (the default for WPF 
applications) disables WM_TOUCH messages. As a result, to use WM_TOUCH to receive touch messages from a 
WPF window, you must disable the built-in stylus support in WPF. This is applicable in a scenario such as a WPF 
window hosting a component that uses WM_TOUCH. 

To disable WPF listening to stylus input, remove any tablet support added by the WPF window. 


Example 


The following sample code shows how to remove the default tablet platform support by using reflection. 


public static void DisableWPFTabletSupport() 

{ 

// Get a collection of the tablet devices for this window. 

TabletDeviceCollection devices = System.Windows.Input.Tablet.TabletDevicesj 

if (devices.Count > 0) 

{ 

// Get the Type of InputManager. 

Type inputManagerType = typeof(System.Windows.Input.InputManager); 

// Call the StylusLogic method on the InputManager.Current instance, 
object StylusLogic = inputManagerType.InvokeMember("StylusLogic"j 

BindingFlags.GetProperty | BindingFlags.Instance | BindingFlags.NonPublic, 
null^ InputManager.Currents null); 

if (StylusLogic != null) 

{ 

// Get the type of the StylusLogic returned from the call to StylusLogic. 

Type stylusLogicType = StylusLogic.GetType(); 


// Loop until there are no more devices to remove, 
while (devices.Count > 0) 

{ 

// Remove the first tablet device in the devices collection. 

StylusLogicType.InvokeMember("OnTabletRemoved"j 

BindingFlags.InvokeMethod | BindingFlags.Instance | BindingFlags.NonPubliCj 
null^ stylusLogiCj new object[] { (uint)0 }); 

} 

} 


} 


} 


See also 


• Intercepting Input from the Stylus 





Drag and Drop 
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Windows Presentation Foundation (WPF) provides a highly flexible drag and drop infrastructure which supports 
dragging and dropping of data within both WPF applications as well as other Windows applications. 

In This Section 

Drag and Drop Overview 
Data and Data Objects 

Walkthrough: Enabling Drag and Drop on a User Control 
Flow-to Topics 

Reference 

DataFormat 

Data Object 

DragDrop 

DragDropEffects 

DragEventFlandler 

TextDataFormat 


Related Sections 




Drag and Drop Overview 
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This topic provides an overview of drag-and-drop support in Windows Presentation Foundation (WPF) 
applications. Drag-and-drop commonly refers to a method of data transfer that involves using a mouse (or some 
other pointing device) to select one or more objects, dragging these objects over some desired drop target in the 
user interface (Ul), and dropping them. 

Drag-and-Drop Support in WPF 

Drag-and-drop operations typically involve two parties: a drag source from which the dragged object originates 
and a drop target which receives the dropped object. The drag source and drop target may be Ul elements in the 
same application or a different application. 

The type and number of objects that can be manipulated with drag-and-drop is completely arbitrary. For example, 
files, folders, and selections of content are some of the more common objects manipulated through drag-and- 
drop operations. 

The particular actions performed during a drag-and-drop operation are application specific, and often determined 
by context. For example, dragging a selection of files from one folder to another on the same storage device 
moves the files by default, whereas dragging files from a Universal Naming Convention (UNC) share to a local 
folder copies the files by default. 

The drag-and-drop facilities provided by WPF are designed to be highly flexible and customizable to support a 
wide variety of drag-and-drop scenarios. Drag-and-drop supports manipulating objects within a single 
application, or between different applications. Dragging-and-dropping between WPF applications and other 
Windows applications is also fully supported. 

In WPF, any UlElement or ContentElement can participate in drag-and-drop. The events and methods required for 
drag-and-drop operations are defined in the DragDrop class. The UlElement and ContentElement classes contain 
aliases for the DragDrop attached events so that the events appear in the class members list when a UlElement or 
ContentElement is inherited as a base element. Event handlers that are attached to these events are attached to the 
underlying DragDrop attached event and receive the same event data instance. For more information, see the 
UlElement.Drop event. 


IMPORTANT 

OLE drag-and-drop does not work while in the Internet zone. 


Data Transfer 

Drag-and-drop is part of the more general area of data transfer. Data transfer includes drag-and-drop and copy- 
and-paste operations. A drag-and-drop operation is analogous to a copy-and-paste or cut-and-paste operation 
that is used to transfer data from one object or application to another by using the system clipboard. Both types of 
operations require: 

• A source object that provides the data. 

• A way to temporarily store the transferred data. 


• A target object that receives the data. 






In a copy-and-paste operation, the system clipboard is used to temporarily store the transferred data; in a drag- 
and-drop operation, a DataObject is used to store the data. Conceptually, a data object consists of one or more 
pairs of an Object that contains the actual data, and a corresponding data format identifier. 

The drag source initiates a drag-and-drop operation by calling the static DragDrop.DoDragDrop method and 
passing the transferred data to it. The DoDragDrop method will automatically wrap the data in a DataObject if 
necessary. For greater control over the data format, you can wrap the data in a DataObject before passing it to the 
DoDragDrop method. The drop target is responsible for extracting the data from the DataObject. For more 
information about working with data objects, see Data and Data Objects. 

The source and target of a drag-and-drop operation are Ul elements; however, the data that is actually being 
transferred typically does not have a visual representation. You can write code to provide a visual representation 
of the data that is dragged, such as occurs when dragging files in Windows Explorer. By default, feedback is 
provided to the user by changing the cursor to represent the effect that the drag-and-drop operation will have on 
the data, such as whether the data will be moved or copied. 

Drag-and-Drop Effects 

Drag-and-drop operations can have different effects on the transferred data. For example, you can copy the data 
or you can move the data. WPF defines a DragDropEffects enumeration that you can use to specify the effect of a 
drag-and-drop operation. In the drag source, you can specify the effects that the source will allow in the 
DoDragDrop method. In the drop target, you can specify the effect that the target intends in the Effects property of 
the DragEventArgs class. When the drop target specifies its intended effect in the DragOver event, that 
information is passed back to the drag source in the GiveFeedback event. The drag source uses this information to 
inform the user what effect the drop target intends to have on the data. When the data is dropped, the drop target 
specifies its actual effect in the Drop event. That information is passed back to the drag source as the return value 
of the DoDragDrop method. If the drop target returns an effect that is not in the drag sources list of 
aiiowedEffects , the drag-and-drop operation is cancelled without any data transfer occurring. 

It is important to remember that in WPF, the DragDropEffects values are only used to provide communication 
between the drag source and the drop target regarding the effects of the drag-and-drop operation. The actual 
effect of the drag-and-drop operation depends on you to write the appropriate code in your application. 

For example, the drop target might specify that the effect of dropping data on it is to move the data. However, to 
move the data, it must be both added to the target element and removed from the source element. The source 
element might indicate that it allows moving the data, but if you do not provide the code to remove the data from 
the source element, the end result will be that the data is copied, and not moved. 

Drag-and-Drop Events 

Drag-and-drop operations support an event driven model. Both the drag source and the drop target use a 
standard set of events to handle drag-and-drop operations. The following tables summarize the standard drag- 
and-drop events. These are attached events on the DragDrop class. For more information about attached events, 
see Attached Events Overview. 

Drag Source Events 

EVENT SUMMARY 

GiveFeedback This event occurs continuously during a drag-and-drop 

operation, and enables the drop source to give feedback 
information to the user. This feedback is commonly given by 
changing the appearance of the mouse pointer to indicate the 
effects allowed by the drop target. This is a bubbling event. 



EVENT 


SUMMARY 


QueryContinueDrag 

This event occurs when there is a change in the keyboard or 
mouse button states during a drag-and-drop operation, and 
enables the drop source to cancel the drag-and-drop 
operation depending on the key/button states. This is a 
bubbling event. 

PreviewGiveFeedback 

Tunneling version of GiveFeedback. 

PreviewQueryContinueDrag 

Tunneling version of QueryContinueDrag. 

Drop Target Events 


EVENT 

SUMMARY 

DragEnter 

This event occurs when an object is dragged into the drop 
target's boundary. This is a bubbling event. 

Drag Leave 

This event occurs when an object is dragged out of the drop 
target's boundary. This is a bubbling event. 

DragOver 

This event occurs continuously while an object is dragged 
(moved) within the drop target's boundary. This is a bubbling 
event. 

Drop 

This event occurs when an object is dropped on the drop 
target. This is a bubbling event. 

PreviewDragEnter 

Tunneling version of DragEnter. 

P reviewDrag Leave 

Tunneling version of DragLeave. 

PreviewDragOver 

Tunneling version of DragOver. 

PreviewDrop 

Tunneling version of Drop. 


To handle drag-and-drop events for instances of an object, add handlers for the events listed in the preceding 
tables. To handle drag-and-drop events at the class level, override the corresponding virtual On*Event and 
On*PreviewEvent methods. For more information, see Class Handling of Routed Events by Control Base Classes. 

Implementing Drag-and-Drop 

A Ul element can be a drag source, a drop target, or both. To implement basic drag-and-drop, you write code to 
initiate the drag-and-drop operation and to process the dropped data. You can enhance the drag-and-drop 
experience by handling optional drag-and-drop events. 

To implement basic drag-and-drop, you will complete the following tasks: 

• Identify the element that will be a drag source. A drag source can be a UlElement or a ContentElement. 

• Create an event handler on the drag source that will initiate the drag-and-drop operation. The event is 
typically the MouseMove event. 

• In the drag source event handler, call the DoDragDrop method to initiate the drag-and-drop operation. In 
the DoDragDrop call, specify the drag source, the data to be transferred, and the allowed effects. 


• Identify the element that will be a drop target. A drop target can be UlElement or a ContentElement. 

• On the drop target, set the AllowDrop property to true. 

• In the drop target, create a Drop event handler to process the dropped data. 

• In the Drop event handler, extract the data from the DragEventArgs by using the GetDataPresent and 
GetData methods. 

• In the Drop event handler, use the data to perform the desired drag-and-drop operation. 

You can enhance your drag-and-drop implementation by creating a custom DataObject and by handling optional 
drag source and drop target events, as shown in the following tasks: 

• To transfer custom data or multiple data items, create a DataObject to pass to the DoDragDrop method. 

• To perform additional actions during a drag, handle the DragEnter, DragOver, and DragLeave events on the 
drop target. 

• To change the appearance of the mouse pointer, handle the GiveFeedback event on the drag source. 

• To change how the drag-and-drop operation is canceled, handle the QueryContinueDrag event on the drag 
source. 

Drag-and-Drop Example 

This section describes how to implement drag-and-drop for an Ellipse element. The Ellipse is both a drag source 
and a drop target. The transferred data is the string representation of the ellipse's Fill property. The following 
XAML shows the Ellipse element and the drag-and-drop related events that it handles. For complete steps on how 
to implement drag-and-drop, see Walkthrough: Enabling Drag and Drop on a User Control. 

<Ellipse Height="50" Width="50" Fill="Green" 

MouseMove="ellipse_MouseMove" 

GiveFeedbacl<="ellipse_GiveFeedback" 

AllowDrop="True" 

Dr'agEnter="ellipse_DragFnter" DragLeave="ellipse_DnagLeave" 

Dr'agOver'="ellipse_Dr'agOver'" Dr'op="ellipse_Drop" /> 

Enabling an Element to be a Drag Source 

An object that is a drag source is responsible for: 

• Identifying when a drag occurs. 

• Initiating the drag-and-drop operation. 

• Identifying the data to be transferred. 

• Specifying the effects that the drag-and-drop operation is allowed to have on the transferred data. 

The drag source may also give feedback to the user regarding the allowed actions (move, copy, none), and can 
cancel the drag-and-drop operation based on additional user input, such as pressing the ESC key during the drag. 

It is the responsibility of your application to determine when a drag occurs, and then initiate the drag-and-drop 
operation by calling the DoDragDrop method. Typically, this is when a MouseMove event occurs over the element 
to be dragged while a mouse button is pressed. The following example shows how to initiate a drag-and-drop 
operation from the MouseMove event handler of an Ellipse element to make it a drag source. The transferred data 
is the string representation of the ellipse's Fill property. 




private void ellipse_MouseMove(object sender, MouseEventArgs e) 

{ 

Ellipse ellipse = sender as Ellipse; 

if (ellipse != null && e.LeftButton == MouseButtonState.Pressed) 
{ 

DragDrop.DoDragDropC ellipse, 

ellipse.Fill.ToStringO, 

DragDropEffects.Copy); 

} 

} 


Private Sub Ellipse_MouseMove(ByVal sender As System.Object, ByVal e As System.Windows.Input.MouseEventArgs) 
Dim ellipse = TryCast(sender, Ellipse) 

If ellipse IsNot Nothing AndAlso e.LeftButton = MouseButtonState.Pressed Then 
DragDrop.DoDragDropCellipse, ellipse.Fill.ToString(), DragDropEffects.Copy) 

End If 
End Sub 


Inside of the MouseMove event handler, call the DoDragDrop method to initiate the drag-and-drop operation. The 
DoDragDrop method takes three parameters: 

• dragSource - A reference to the dependency object that is the source of the transferred data; this is 
typically the source of the MouseMove event. 

• data - An object that contains the transferred data, wrapped in a DataObJect. 

• aiiowedEffects - One of the DragDropEffects enumeration values that specifies the permitted effects of the 
drag-and-drop operation. 

Any serializable object can be passed in the data parameter. If the data is not already wrapped in a DataObject, it 
will automatically be wrapped in a new DataObject. To pass multiple data items, you must create the DataObject 
yourself, and pass it to the DoDragDrop method. For more information, see Data and Data Objects. 

The aiiowedEffects parameter is used to specify what the drag source will allow the drop target to do with the 
transferred data. The common values for a drag source are Copy, Move, and All. 


NOTE 

The drop target is also able to specify what effects it intends in response to the dropped data. For example, if the drop 
target does not recognize the data type to be dropped, it can refuse the data by setting its allowed effects to None. It 
typically does this in its DragOver event handler. 


A drag source can optionally handle the GiveFeedback and QueryContinueDrag events. These events have default 
handlers that are used unless you mark the events as handled. You will typically ignore these events unless you 
have a specific need to change their default behavior. 

The GiveFeedback event is raised continuously while the drag source is being dragged. The default handler for this 
event checks whether the drag source is over a valid drop target. If it is, it checks the allowed effects of the drop 
target. It then gives feedback to the end user regarding the allowed drop effects. This is typically done by changing 
the mouse cursor to a no-drop, copy, or move cursor. You should only handle this event if you need to use custom 
cursors to provide feedback to the user. If you handle this event, be sure to mark it as handled so that the default 
handler does not override your handler. 

The QueryContinueDrag event is raised continuously while the drag source is being dragged. You can handle this 
event to determine what action ends the drag-and-drop operation based on the state of the ESC, SHIFT, CTRL, and 
ALT keys, as well as the state of the mouse buttons. The default handler for this event cancels the drag-and-drop 








operation if the ESC key is pressed, and drops the data if the mouse button is released. 

Caution 

These events are raised continuously during the drag-and-drop operation. Therefore, you should avoid resource¬ 
intensive tasks in the event handlers. For example, use a cached cursor instead of creating a new cursor each time 
the GiveFeedback event is raised. 

Enabling an Element to be a Drop Target 

An object that is a drop target is responsible for: 

• Specifying that it is a valid drop target. 

• Responding to the drag source when it drags over the target. 

• Checking that the transferred data is in a format that it can receive. 

• Processing the dropped data. 

To specify that an element is a drop target, you set its AllowDrop property to true . The drop target events will 
then be raised on the element so that you can handle them. During a drag-and-drop operation, the following 
sequence of events occurs on the drop target: 

1. DragEnter 

2. DragOver 

3. DragLeave or Drop 

The DragEnter event occurs when the data is dragged into the drop target's boundary. You typically handle this 
event to provide a preview of the effects of the drag-and-drop operation, if appropriate for your application. Do 
not set the DragEventArgs.Effects property in the DragEnter event, as it will be overwritten in the DragOver event. 

The following example shows the DragEnter event handler for an Ellipse element. This code previews the effects of 
the drag-and-drop operation by saving the current Fill brush. It then uses the GetDataPresent method to check 
whether the DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, 
the data is extracted using the GetData method. It is then converted to a Brush and applied to the ellipse. The 
change is reverted in the DragLeave event handler. If the data cannot be converted to a Brush, no action is 
performed. 


private Brush _previousFill = null; 

private void ellipse_DragEnter(object sender, DragEventArgs e) 

{ 

Ellipse ellipse = sender as Ellipse; 
if (ellipse != null) 

{ 

// Save the current Fill brush so that you can revert back to this value in DragLeave. 
_previousFill = ellipse.Fill; 

// If the DataObject contains string data, extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brush, convert it. 

BrushConverter converter = new BrushConverter(); 
if (converter.IsValid(dataString)) 

{ 

Brush newFill = (Brush)converter.ConvertFromString(dataString); 
ellipse.Fill = newFill; 

} 

} 

} 

} 


Private _previousFill As Brush = Nothing 

Private Sub Ellipse_DragEnter(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs) 
Dim ellipse = TryCast(sender, Ellipse) 

If ellipse IsNot Nothing Then 

' Save the current fill brush so that you can revert back to this value in DragLeave. 
_previousEill = ellipse.fill 

' If the DataObject contains string data, extract it. 

If e.Data.GetDataPresent(DataEormats.StringFormat) Then 

Dim dataString = e.Data.GetData(DataPormats.StringPormat) 

' If the string can be converted into a Brush, convert it. 

Dim converter As New BrushConverter() 

If converter.Is\/alid(dataString) Then 

Dim newFill As Brush = CType(converter.ConvertFromString(dataString), Brush) 
ellipse.Fill = newFill 
End If 
End If 
End If 
End Sub 


The DragOver event occurs continuously while the data is dragged over the drop target This event is paired with 
the GiveFeedback event on the drag source. In the DragOver event handler, you typically use the GetDataPresent 
and GetData methods to check whether the transferred data is in a format that the drop target can process. You 
can also check whether any modifier keys are pressed, which will typically indicate whether the user intends a 
move or copy action. After these checks are performed, you set the DragEventArgs.Effects property to notify the 
drag source what effect dropping the data will have. The drag source receives this information in the 
GiveFeedback event args, and can set an appropriate cursor to give feedback to the user. 

The following example shows the DragOver event handler for an Ellipse element. This code checks to see if the 
DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, it sets the 
DragEventArgs.Effects property to Copy. This indicates to the drag source that the data can be copied to the 
ellipse. If the data cannot be converted to a Brush, the DragEventArgs.Effects property is set to None. This indicates 
to the drag source that the ellipse is not a valid drop target for the data. 



private void ellipse_DragOver(object sendeOj DragEventArgs e) 

{ 

e.Effects = DragDropEffects.None; 

// If the DataObject contains string data^ extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brush, allow copying. 
BrushConverter converter = new BrushConverter()j 
if (converter.IsValid(dataString)) 

{ 

e.Effects = DragDropEffects.Copy | DragDropEffects.Move; 

} 

} 

} 


Private Sub Ellipse_DragOver(By\/al sender As System.Object, ByVal e As System.Windows.DragEventArgs) 
e.Effects = DragDropEffects.None 

' If the DataObject contains string data, extract it. 

If e.Data.GetDataPresent(DataFormats.StringFormat) Then 

Dim dataString = e.Data.GetData(DataFormats.StringFormat) 

' If the string can be converted into a Brush, convert it. 

Dim converter As New BrushConverter() 

If converter.Is\/alid(dataString) Then 

e.Effects = DragDropEffects.Copy Or DragDropEffects.Move 
End If 
End If 
End Sub 


The DragLeave event occurs when the data is dragged out of the target's boundary without being dropped. You 
handle this event to undo anything that you did in the DragEnter event handler. 

The following example shows the DragLeave event handler for an Ellipse element. This code undoes the preview 
performed in the DragEnter event handler by applying the saved Brush to the ellipse. 

private void ellipse_DragLeave(object sender, DragEventArgs e) 

{ 

Ellipse ellipse = sender as Ellipse; 
if (ellipse != null) 

{ 

ellipse.Fill = _previousFill; 

} 

} 


Private Sub Ellipse_DragLeave(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs) 
Dim ellipse = TryCast(sender, Ellipse) 

If ellipse IsNot Nothing Then 
ellipse.Fill = _previousFill 
End If 
End Sub 


The Drop event occurs when the data is dropped over the drop target; by default, this happens when the mouse 
button is released. In the Drop event handler, you use the GetData method to extract the transferred data from the 
DataObject and perform any data processing that your application requires. The Drop event ends the drag-and- 
drop operation. 




The following example shows the Drop event handler for an Ellipse element. This code applies the effects of the 
drag-and-drop operation, and is similar to the code in the DragEnter event handler. It checks to see if the 
DataObject being dragged over the ellipse contains string data that can be converted to a Brush. If so, the Brush is 
applied to the ellipse. If the data cannot be converted to a Brush, no action is performed. 

private void ellipse_Drop(object sender, DragEventArgs e) 

{ 

Ellipse ellipse = sender as Ellipse; 
if (ellipse != null) 

{ 

// If the DataObject contains string data, extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brush, 

// convert it and apply it to the ellipse. 

BrushConverter converter = new BrushConverter(); 
if (converter.IsValid(dataString)) 

{ 

Brush newFill = (Brush)converter.ConvertFromString(dataString); 
ellipse.Fill = newFill; 

} 

} 

} 

} 


Private Sub Ellipse_Drop(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs) 
Dim ellipse = TryCast(sender, Ellipse) 

If ellipse IsNot Nothing Then 

' If the DataObject contains string data, extract it. 

If e.Data.GetDataPresent(DataFormats.StringFormat) Then 

Dim dataString = e.Data.GetData(DataFormats.StringFormat) 

' If the string can be converted into a Brush, convert it. 

Dim converter As New BrushConverter() 

If converter.IsValid(dataString) Then 

Dim newFill As Brush = CType(converter.ConvertFromString(dataString), Brush) 
ellipse.Fill = newFill 
End If 
End If 
End If 
End Sub 


See also 

• Clipboard 

• Walkthrough: Enabling Drag and Drop on a User Control 

• How-to Topics 

• Drag and Drop 
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Data that is transferred as part of a drag-and-drop operation is stored in a data object. Conceptually, a data object 
consists of one or more of the following pairs: 

• An Object that contains the actual data. 

• A corresponding data format identifier. 

The data itself can consist of anything that can be represented as a base Object. The corresponding data format is a 
string or Type that provides a hint about what format the data is in. Data objects support hosting multiple 
data/data format pairs; this enables a single data object to provide data in multiple formats. 

Data Objects 

All data objects must implement the IDataObject interface, which provides the following standard set of methods 
that enable and facilitate data transfer. 


METHOD 

SUMMARY 

GetData 

Retrieves a data object in a specified data format. 

GetDataPresent 

Checks to see whether the data is available in, or can be 
converted to, a specified format. 

GetFormats 

Returns a list of formats that the data in this data object is 
stored in, or can be converted to. 

SetData 

Stores the specified data in this data object. 


WPF provides a basic implementation of IDataObject in the DataObject class. The stock DataObject class is 
sufficient for many common data transfer scenarios. 

There are several pre-defined formats, such as bitmap, CSV, file, HTML, RTF, string, text, and audio. For information 
about pre-defined data formats provided with WPF, see the DataFormats class reference topic. 

Data objects commonly include a facility for automatically converting data stored in one format to a different 
format while extracting data; this facility is referred to as auto-convert. When querying for the data formats 
available in a data object, auto-convertible data formats can be filtered from native data formats by calling the 
GetFormatsfBoolean) or GetDataPresent(String, Boolean) method and specifying the autoConvert parameter as 
false . When adding data to a data object with the SetDatafString, Object, Boolean) method, auto-conversion of 
data can be prohibited by setting the autoConvert parameter to false . 

Working with Data Objects 

This section describes common techniques for creating and working with data objects. 

Creating New Data Objects 

The DataObject class provides several overloaded constructors that facilitate populating a new DataObject instance 
with a single data/data format pair. 







The following example code creates a new data object and uses one of the overloaded constructors 
DataObJect(DataObject{String, Object)) to initialize the data object with a string and a specified data format. In this 
case, the data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. 
Auto-conversion of the stored data is allowed by default. 

string stringData = "Some string data to store..."j 
string dataFormat = DataFormats.UnicodeText; 

DataObject dataObject = new DataObject(dataFormat, stringData)j 


Dim StringData As String = "Some string data to store..." 

Dim dataFormat As String = DataFormats.UnicodeText 

Dim dataObject As New DataObject(dataFormat, stringData) 


For more examples of code that creates a data object, see Create a Data Object. 

Storing Data in Multiple Formats 

A single data object is able to store data in multiple formats. Strategic use of multiple data formats within a single 
data object potentially makes the data object consumable by a wider variety of drop targets than if only a single 
data format could be represented. Note that, in general, a drag source must be agnostic about the data formats 
that are consumable by potential drop targets. 

The following example shows how to use the SetDatafString, Object) method to add data to a data object in 
multiple formats. 

DataObject dataObject = new DataObject(); 

string sourceData = "Some string data to store..."j 

// Encode the source string into Unicode byte arrays. 
byte[] UnicodeText = Encoding.Unicode.GetBytes(sourceData)j // UTF-16 
byte[] utfSText = Encoding.UTF8.GetBytes(sourceData); 
byte[] utfBZText = Encoding.UTF32.GetBytes(sourceData)j 

// The DataFormats class does not provide data format fields for denoting 
// UTF-32 and UTF-8j which are seldom used in practice; the following strings 
// will be used to identify these "custom" data formats, 
string utf32DataFormat = "UTF-32"; 
string utf8DataFormat = "UTF-8"; 

// Store the text in the data object^ letting the data object choose 
// the data format (which will be DataFormats.Text in this case). 
dataObject.SetData(sourceData); 

// Store the Unicode text in the data object. Text data can be automatically 
// converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 

// Therefore^ explicitly converting the source text to Unicode is generally unnecessary, and 
// is done here as an exercise only. 

dataObject.SetData(DataFormats.UnicodeText, UnicodeText); 

// Store the UTF-8 text in the data object... 
dataObject.SetData(utf8DataFormat, utf8Text); 

// Store the UTF-32 text in the data object... 
dataObj ect.SetData(utf32DataFormat, utf32Text); 




Dim dataObject As New DataObject() 

Dim sounceData As String = "Some string data to store..." 

' Encode the source string into Unicode byte arrays. 

Dim unicodeText() As Byte = Encoding.Unicode.GetBytes(sourceData) ' UTF-16 
Dim utfSTextO As Byte = Encoding.UTF8.GetBytes(sourceData) 

Dim utf32Text() As Byte = Encoding.UTF32.GetBytes(sourceData) 

’ The DataFormats class does not provide data format fields for denoting 
' UTF-32 and UTF-8, which are seldom used in practice; the following strings 
' will be used to identify these "custom" data formats. 

Dim utf32DataFormat As String = "UTF-32" 

Dim utf8DataFormat As String = "UTF-8" 

' Store the text in the data object^ letting the data object choose 
' the data format (which will be DataFormats.Text in this case). 
dataObject.SetData(sourceData) 

' Store the Unicode text in the data object. Text data can be automatically 
' converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 

' Thereforej explicitly converting the source text to Unicode is generally unnecessary^ and 
' is done here as an exercise only. 

dataObject.SetData(DataFormats.UnicodeTextj unicodeText) 

' Store the UTF-8 text in the data object... 
dataObject.SetData(utf8DataFormatj utf8Text) 

' Store the UTF-32 text in the data object... 
dataObj ect.SetData(utf32DataFormat, utf32Text) 


Querying a Data Object for Available Formats 

Because a single data object can contain an arbitrary number of data formats, data objects include facilities for 
retrieving a list of available data formats. 

The following example code uses the GetFormats overload to get an array of strings denoting all data formats 
available in a data object (both native and by auto-convert). 

DataObject dataObject = new DataObject("Some string data to store..."); 

// Get an array of strings, each string denoting a data format 
// that is available in the data object. This overload of GetDataFormats 
// returns all available data formats, native and auto-convertible. 
string[] dataFormats = dataObject.GetFormats(); 

// Get the number of data formats present in the data object, including both 
// auto-convertible and native data formats, 
int numberOfDataFormats = dataFormats.Length; 

// To enumerate the resulting array of data formats, and take some action when 

// a particular data format is found, use a code structure similar to the following. 

foreach (string dataFormat in dataFormats) 

{ 

if (dataFormat == DataFormats.Text) 

{ 

// Take some action if/when data in the Text data format is found, 
break; 

} 

else if(dataFormat == DataFormats.StringFormat) 

{ 

// Take some action if/when data in the string data format is found, 
break; 

} 

} 




Dim dataObject As New DataObject("Some string data to store...") 

' Get an array of strings^ each string denoting a data format 
' that is available in the data object. This overload of GetDataFormats 
' returns all available data formats^ native and auto-convertible. 

Dim dataFormats() As String = dataObject.GetFormats() 

' Get the number of data formats present in the data object, including both 
' auto-convertible and native data formats. 

Dim numberOfDataFormats As Integer = dataFormats.Length 

' To enumerate the resulting array of data formats, and take some action when 
' a particular data format is found, use a code structure similar to the following. 
For Each dataFormat As String In dataFormats 

If dataFormat = System.Windows.DataFormats.Text Then 

' Take some action if/when data in the Text data format is found. 

Exit For 

Elself dataFormat = System.Windows.DataFormats.StringFormat Then 

' Take some action if/when data in the string data format is found. 

Exit For 
End If 

Next dataEormat 


For more examples of code that queries a data object for available data formats, see List the Data Formats in a 
Data Object. For examples of querying a data object for the presence of a particular data format, see Determine if a 
Data Format is Present in a Data Object. 

Retrieving Data from a Data Object 

Retrieving data from a data object in a particular format simply involves calling one of the GetData methods and 
specifying the desired data format. One of the GetDataPresent methods can be used to check for the presence of a 
particular data format. GetData returns the data in an Object; depending on the data format, this object can be cast 
to a type-specific container. 

The following example code uses the GetDataPresent(String) overload to check if a specified data format is 
available (native or by auto-convert). If the specified format is available, the example retrieves the data by using 
the GetData(String) method. 

DataObject dataObject = new DataObject("Some string data to store...")j 

string desiredFormat = DataFormats.UnicodeTextj 
byte[] data = null; 

// Use the GetDataPresent method to check for the presence of a desired data format. 

// This particular overload of GetDataPresent looks for both native and auto-convertible 
// data formats. 

if (dataObject.GetDataPresent(desiredFormat)) 

{ 

// If the desired data format is present, use one of the GetData methods to retrieve the 
// data from the data object. 

data = dataObject.GetData(desiredFormat) as byte[]; 

} 




Dim dataObject As New DataObject("Some string data to store...") 

Dim desiredFormat As String = DataFormats.UnicodeText 
Dim data() As Byte = Nothing 

' Use the GetDataPresent method to check for the presence of a desired data format. 

' This particular overload of GetDataPresent looks for both native and auto-convertible 
' data formats. 

If dataObject.GetDataPresent(desiredFormat) Then 

' If the desired data format is present, use one of the GetData methods to retrieve the 
' data from the data object. 

data = TryCast(dataObject.GetData(desiredFormat), Byte()) 

End If 


For more examples of code that retrieves data from a data object, see Retrieve Data in a Particular Data Format. 

Removing Data From a Data Object 

Data cannot be directly removed from a data object. To effectively remove data from a data object, follow these 
steps: 

1. Create a new data object that will contain only the data you want to retain. 

2. "Copy" the desired data from the old data object to the new data object. To copy the data, use one of the 
GetData methods to retrieve an Object that contains the raw data, and then use one of the SetData methods 
to add the data to the new data object. 

3. Replace the old data object with the new one. 


NOTE 

The SetData methods only add data to a data object; they do not replace data, even if the data and data format are exactly 
the same as a previous call. Calling SetData twice for the same data and data format will result in the data/data format being 
present twice in the data object. 




Walkthrough: Enabling Drag and Drop on a User 
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This walkthrough demonstrates how to create a custom user control that can participate in drag-and-drop data 
transfer in Windows Presentation Foundation (WPF). 

In this walkthrough, you will create a custom WPF UserControl that represents a circle shape. You will implement 
functionality on the control to enable data transfer through drag-and-drop. For example, if you drag from one 
Circle control to another, the Fill color data is copied from the source Circle to the target. If you drag from a Circle 
control to a TextBox, the string representation of the Fill color is copied to the TextBox. You will also create a small 
application that contains two panel controls and a TextBox to test the drag-and-drop functionality. You will write 
code that enables the panels to process dropped Circle data, which will enable you to move or copy Circles from 
the Children collection of one panel to the other. 

This walkthrough illustrates the following tasks: 

• Create a custom user control. 

• Enable the user control to be a drag source. 

• Enable the user control to be a drop target. 

• Enable a panel to receive data dropped from the user control. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Create the Application Project 

In this section, you will create the application infrastructure, which includes a main page with two panels and a 
TextBox. 

1. Create a new WPF Application project in Visual Basic or Visual C# named DragOropExampie . For more 
information, see Walkthrough: My first WPF desktop application. 

2. Open MainWindow.xaml. 

3. Add the following markup between the opening and closing Grid tags. 

This markup creates the user interface for the test application. 





<Grid.ColumnDefinitions> 
<ColumnDefinition /> 
<ColumnDefinition /> 

</Grid.ColumnDefinitions> 

<StackPanel Gnid.Column="0" 

Bacl<gnound="Beige"> 
<TextBox Width="Auto" Margin="2" 
Text="green"/> 

</StackPanel> 

<StackPanel Gnid.Column="l" 

Backgnound="Bisque"> 

</StackPanel> 


Add a New User Control to the Project 

In this section, you will add a new user control to the project. 

1. On the Project menu, select Add User Control. 

2. In the Add New Item dialog box, change the name to Circle.xami , and click Add. 

Circle.xamI and its code-behind is added to the project. 

3. Open Circle.xamI. 

This file will contain the user interface elements of the user control. 

4. Add the following markup to the root Grid to create a simple user control that has a blue circle as its Ul. 

<Ellipse x:Name="circleUI" 

Height="100" Width="100" 

Fill="Blue" /> 


5. Open Circle.xaml.es or Circle.xaml.vb. 

6. In C#, add the following code after the parameterless constructor to create a copy constructor. In Visual 
Basic, add the following code to create both a parameterless constructor and a copy constructor. 

In order to allow the user control to be copied, you add a copy constructor method in the code-behind file. 
In the simplified Circle user control, you will only copy the Fill and the size of the of the user control. 

public Cir'cle(Circle c) 

{ 

InitializeComponent(); 

this.cincleUI.Height = c-cincleUI.Height; 
this.cincleUI.Width = c.circleUI.Height; 
this.circleUI.Fill = c.cincleUI.Fill; 

} 






Public Sub New() 

' This call is required by the designer. 
InitializeComponentO 
End Sub 

Public Sub New(ByVal c As Circle) 
InitializeComponentO 
Me.circleUI.Height = c.circleUI.Height 
Me.circleUI.Width = c.circleUI.Height 
Me.circleUI.Fill = c.circleUI.Fill 
End Sub 


Add the user control to the main window 

1. Open MainWindow.xaml. 

2. Add the following XAML to the opening Window tag to create an XML namespace reference to the current 
application. 

xmlns:local="clr-namespace:DragDropExample" 


3. In the first StackPanel, add the following XAML to create two instances of the Circle user control in the first 
panel. 

<localrCircle Margin="2" /> 

<localrCircle Margin="2" /> 


The full XAML for the panel looks like the following. 

<StackPanel Grid.Column="0" 

Bacl<ground="Beige"> 
cTextBox Width="Auto" Margin="2" 
Text="green"/> 

<local:Circle Margin="2" /> 

<local:Circle Margin="2" /> 

</StackPanel> 

<StackPanel Grid.Column="l" 

Background="Bisque"> 

</StackPanel> 


Implement Drag Source Events in the User Control 

In this section, you will override the OnMouseMove method and initiate the drag-and-drop operation. 

If a drag is started (a mouse button is pressed and the mouse is moved), you will package the data to be 
transferred into a DataObject. In this case, the Circle control will package three data items; a string representation 
of its Fill color, a double representation of its height, and a copy of itself 

To initiate a drag-and-drop operation 

1. Open Circle.xaml.cs or Circle.xaml.vb. 

2. Add the following OnMouseMove override to provide class handling for the MouseMove event. 




protected override void OnMouseMove(MouseEventArgs e) 

{ 

base.OnMouseMove(e); 

if (e.LeftButton == MouseButtonState.Pressed) 

{ 

// Package the data. 

DataObject data = new DataObject()j 

data.SetData(DataFormats.StringFormatj circleUI. Fill .ToStringO) j 
data.SetData("Double"j circleUI.Height); 
data.SetData("Object"j this); 

// Inititate the drag-and-drop operation. 

DragDrop.DoDragDrop(this, data^ DragDropFffects.Copy | DragDropEffects.Move); 

} 

} 


Protected Overrides Sub OnMouseMove(By\/al e As System.Windows.Input.MouseEventArgs) 
MyBase.OnMouseMove(e) 

If e.LeftButton = MouseButtonState.Pressed Then 
' Package the data. 

Dim data As New DataObject 

data.SetData(DataFormats.StringFormatj circleUI.Fill.ToString()) 
data.SetData("Double"j circleUI.Height) 
data.SetData("Object"j He) 

' Inititate the drag-and-drop operation. 

DragDrop.DoDragDrop(Mej data, DragDropFffects.Copy Or DragDropEffects.Move) 
End If 
End Sub 


This OnMouseMove override performs the following tasks: 

• Checks whether the left mouse button is pressed while the mouse is moving. 

• Packages the Circle data into a DataObject. In this case, the Circle control packages three data items; a 
string representation of its Fill color, a double representation of its height, and a copy of itself 

• Calls the static DragDrop.DoDragDrop method to initiate the drag-and-drop operation. You pass the 
following three parameters to the DoDragDrop method: 

o dragSource - A reference to this control. 

o data - The DataObject created in the previous code. 

o aiiowedEffects - The allowed drag-and-drop operations, which are Copy or Move. 

3. Press F5 to build and run the application. 

4. Click one of the Circle controls and drag it over the panels, the other Circle, and the TextBox. When dragging 
over the TextBox, the cursor changes to indicate a move. 

5. While dragging a Circle over the TextBox, press the Ctrl key. Notice how the cursor changes to indicate a 
copy. 

6. Drag and drop a Circle onto the TextBox. The string representation of the Circle's fill color is appended to the 
TextBox. 







By default, the cursor will change during a drag-and-drop operation to indicate what effect dropping the data will 
have. You can customize the feedback given to the user by handling the GiveFeedback event and setting a different 
cursor. 

Give feedback to the user 

1. Open Circle.xaml.es or Circle.xaml.vb. 

2. Add the following OnGiveFeedback override to provide class handling for the GiveFeedback event. 

protected override void OnGiveFeedback(GiveFeedbackEventArgs e) 

{ 

base.OnGiveFeedback(e); 

// These Effects values are set in the drop target's 

// DragOver event handler. 

if (e.Effects.HasFlag(DragDropEffeets.Copy)) 

{ 

Mouse.SetCursor(Cursors.Cross); 

} 

else if (e.Effects.HasFlag(DragDropEffects.Move)) 

{ 

Mouse.SetCursor(Cursors.Pen); 

} 

else 

{ 

Mouse.SetCursor(Cursors.No); 

} 

e.Handled = true; 

} 


Protected Overrides Sub OnGlveFeedback(ByVal e As System.Windows.GiveFeedbackEventArgs) 
MyBase.OnGiveFeedback(e) 

' These Effects values are set in the drop target's 
' DragOver event handler. 

If e.Effects.HasFlag(DragDropEffects.Copy) Then 
Mouse.SetCursor(Cursors.Cross) 

Elself e.Effects.HasFlag(DragDropEffects.Move) Then 
Mouse.SetCursor(Cursors.Pen) 

Else 

Mouse.SetCursor(Cursors.No) 

End If 

e.Handled = True 
End Sub 


This OnGiveFeedback override performs the following tasks: 












• Checks the Effects values that are set in the drop target's DragOver event handler. 

• Sets a custom cursor based on the Effects value. The cursor is intended to give visual feedback to the 
user about what effect dropping the data will have. 

3. Press F5 to build and run the application. 


4. Drag one of the Circle controls over the panels, the other Circle, and the TextBox. Notice that the cursors are 
now the custom cursors that you specified in the OnGiveFeedback override. 



the drag-and-drop operation. The feedback cursor is always set by the drag source. 


Implement Drop Target Events in the User Control 

In this section, you will specify that the user control is a drop target, override the methods that enable the user 
control to be a drop target, and process the data that is dropped on it. 

To 

1 . 

2 . 


The OnDrop method is called when the AllowDrop property is set to true and data from the drag source is 
dropped on the Circle user control. In this method, you will process the data that was dropped and apply the data 
to the Circle. 

To process the dropped data 

1. Open Circle.xaml.es or Circle.xaml.vb. 

2. Add the following OnDrop override to provide class handling for the Drop event. 


enable the user control to be a drop target 

Open Circle.xaml. 

In the opening UserControl tag, add the AllowDrop property and set it to true . 

<UserContr'ol x:Class="DragDropWall<through.Circle" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 

xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

xmlns:mc="http://schemas.openxmlformats.ong/markup-compatibility/2006" 

xmlns:d="http://schemas.microsoft.com/expression/blend/2008" 

me:Ignorable="d" 

d:DesignHelght="300" d:DesignWidth="300" 

AllowDrop="True"> 
















protected override void OnDrop(DragEventArgs e) 

{ 

base.OnDrop(e); 

// If the DataObject contains string data, extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brush, 

// convert it and apply it to the ellipse. 

BrushConverter converter = new BrushConverter(); 
if (converter.Is\/alid(dataString)) 

{ 

Brush newFill = (Brush)converter.ConvertFromString(dataString)j 
circleUI.Fill = newFill; 

// Set Effects to notify the drag source what effect 
// the drag-and-drop operation had. 

// (Copy if CTRL is pressed; otherwise, move.) 

if (e.KeyStates.HasFlag(DragDropKeyStates.ControlKey)) 

{ 

e.Effects = DragDropEffects.Copy; 

} 

else 

{ 

e.Effects = DragDropEffects.Move; 

} 

} 

} 

e.Handled = true; 


Protected Overrides Sub OnDrop(ByVal e As System.Windows.DragEventArgs) 
MyBase.OnDrop(e) 

' If the DataObject contains string data, extract it. 

If e.Data.GetDataPresent(DataFormats.StringFormat) Then 

Dim dataString As String = e.Data.GetData(DataFormats.StringFormat) 

' If the string can be converted into a Brush, 

' convert it and apply it to the ellipse. 

Dim converter As New BrushConverter 
If converter.IsValid(dataString) Then 

Dim newFill As Brush = converter.ConvertFromString(dataString) 
circleUI.Fill = newFill 

' Set Effects to notify the drag source what effect 
' the drag-and-drop operation had. 

' (Copy if CTRL is pressed; otherwise, move.) 

If e.KeyStates.HasFlag(DragDropKeyStates.ControlKey) Then 
e.Effects = DragDropEffects.Copy 

Else 

e.Effects = DragDropEffects.Move 
End If 
End If 
End If 

e.Handled = True 
End Sub 


This OnDrop override performs the following tasks: 

• Uses the GetDataPresent method to check if the dragged data contains a string object. 

• Uses the GetData method to extract the string data if it is present. 



• Uses a BrushConverter to try to convert the string to a Brush. 

• If the conversion is successful, applies the brush to the Fill of the Ellipse that provides the Ul of the 
Circle control. 

• Marks the Drop event as handled. You should mark the drop event as handled so that other elements 
that receive this event know that the Circle user control handled it. 

3. Press F5 to build and run the application. 

4. Select the text green in the TextBox. 

5. Drag the text to a Circle control and drop it. The Circle changes from blue to green. 



6. Type the text green in the TextBox. 

7. Select the text gre in the TextBox. 

8. Drag it to a Circle control and drop it. Notice that the cursor changes to indicate that the drop is allowed, but 
the color of the Circle does not change because gre is not a valid color. 

9. Drag from the green Circle control and drop on the blue Circle control. The Circle changes from blue to 
green. Notice that which cursor is shown depends on whether the TextBox or the Circle is the drag source. 

Setting the AllowDrop property to true and processing the dropped data is all that is required to enable an 
element to be a drop target. Flowever, to provide a better user experience, you should also handle the DragEnter, 
DragLeave, and DragOver events. In these events, you can perform checks and provide additional feedback to the 
user before the data is dropped. 

When data is dragged over the Circle user control, the control should notify the drag source whether it can process 
the data that is being dragged. If the control does not know how to process the data, it should refuse the drop. To 
do this, you will handle the DragOver event and set the Effects property. 

To verify that the data drop is allowed 

1. Open Circle.xaml.es or Circle.xaml.vb. 

2. Add the following OnDragOver override to provide class handling for the DragOver event. 














protected override void OnDragOver(DragEventArgs e) 

{ 

base.OnDragOver(e); 

e.Effects = DragDropEffects.None; 

// If the DataObject contains string data, extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brushy allow copying or moving. 
BrushConverter converter = new BrushConverter(); 
if (converter.Is\/alid(dataString)) 

{ 

// Set Effects to notify the drag source what effect 
// the drag-and-drop operation will have. These values are 
// used by the drag source's GiveFeedback event handler. 

// (Copy if CTRL is pressed; otherwise^ move.) 

if (e.KeyStates.HasFlag(DragDropKeyStates.ControlKey)) 

{ 

e.Effects = DragDropEffects.Copy; 

} 

else 

{ 

e.Effects = DragDropEffects.Move; 

} 

} 

} 

e.Handled = true; 


Protected Overrides Sub OnDragOver(ByVal e As System.Windows.DragEventArgs) 
MyBase.OnDragOver(e) 
e.Effects = DragDropEffects.None 

' If the DataObject contains string data^ extract it. 

If e.Data.GetDataPresent(DataFormats.StringFormat) Then 

Dim dataString As String = e.Data.GetData(DataFormats.StringFormat) 

' If the string can be converted into a Brush, allow copying or moving. 
Dim converter As New BrushConverter 
If converter.IsValid(dataString) Then 

' Set Effects to notify the drag source what effect 
' the drag-and-drop operation will have. These values are 
' used by the drag source's GiveFeedback event handler. 

' (Copy if CTRL is pressed; otherwise, move.) 

If e.KeyStates.HasFlag(DragDropKeyStates.ControlKey) Then 
e.Effects = DragDropEffects.Copy 

Else 

e.Effects = DragDropEffects.Move 
End If 
End If 
End If 

e.Handled = True 
End Sub 


This OnDragOver override performs the following tasks: 

• Sets the Effects property to None. 

• Performs the same checks that are performed in the OnDrop method to determine whether the 
Circle user control can process the dragged data. 

• If the user control can process the data, sets the Effects property to Copy or Move. 



3. Press F5 to build and run the application. 

4. Select the text gne in the TextBox. 

5. Drag the text to a Circle control. Notice that the cursor now changes to indicate that the drop is not allowed 
because gne is not a valid color. 

You can further enhance the user experience by applying a preview of the drop operation. For the Circle user 
control, you will override the OnDragEnter and OnDragLeave methods. When the data is dragged over the control, 
the current background Fill is saved in a placeholder variable. The string is then converted to a brush and applied 
to the Ellipse that provides the Circle's Ul. If the data is dragged out of the Circle without being dropped, the 
original Fill value is re-applied to the Circle. 

To preview the effects of the drag-and-drop operation 

1. Open Circle.xaml.es or Circle.xaml.vb. 

2. In the Circle class, declare a private Brush variable named _previousFiii and initialize it to null. 

public partial class Circle : UserControl 

{ 

private Brush _previousFill = null; 

Public Class Circle 

Private _previousFill As Brush = Nothing 


3. Add the following OnDragEnter override to provide class handling for the DragEnter event. 

protected override void OnDragEnter(DragEventArgs e) 

{ 

base.OnDragEnter(e); 

// Save the current Fill brush so that you can revert back to this value in DragLeave. 
_previousFill = circleUI.Fill; 

// If the DataObject contains string data, extract it. 
if (e.Data.GetDataPresent(DataFormats.StringFormat)) 

{ 

string dataString = (string)e.Data.GetData(DataFormats.StringFormat); 

// If the string can be converted into a Brush, convert it. 

BrushConverter converter = new BrushConverter(); 
if (converter.IsValid(dataString)) 

{ 

Brush newFill = (Brush)converter.ConvertFromString(dataString.ToString()); 
circleUI.Fill = newFill; 

} 

} 

} 







Protected Overrides Sub OnDragEnter(By\/al e As System.Windows.DragEventArgs) 
MyBase.OnDragEnter(e) 

_previousFill = circleUI.Fill 

' If the DataObject contains string data^ extract it. 

If e.Data.GetDataPresent(DataFormats.StringFormat) Then 

Dim dataString As String = e.Data.GetData(DataFormats.StringFormat) 

' If the string can be converted into a Brush, convert it. 

Dim converter As IMew BrushConverter 
If converter.IsValid(dataString) Then 

Dim newFill As Brush = converter.ConvertFromString(dataString) 
circleUI.Fill = newFill 
End If 
End If 

e.Handled = True 
End Sub 


This OnDragEnter override performs the following tasks: 

• Saves the Fill property of the Ellipse in the _previousFiii variable. 

• Performs the same checks that are performed in the OnDrop method to determine whether the data 
can be converted to a Brush. 

• If the data is converted to a valid Brush, applies it to the Fill of the Ellipse. 

4. Add the following OnDragLeave override to provide class handling for the DragLeave event. 

protected override void OnDragLeave(DragEventArgs e) 

{ 

base.OnDragLeave(e); 

// Undo the preview that was applied in OnDragEnter. 
circleUI.Fill = _previousFill; 

} 


Protected Overrides Sub OnDragLeave(ByVal e As System.Windows.DragEventArgs) 
MyBase.OnDragLeave(e) 

' Undo the preview that was applied in OnDragEnter. 
circleUI.Fill = _previousFill 
End Sub 


This OnDragLeave override performs the following tasks: 

• Applies the Brush saved in the _previousFiii variable to the Fill of the Ellipse that provides the Ul of the 
Circle user control. 

5. Press F5 to build and run the application. 

6. Select the text green in the TextBox. 

7. Drag the text over a Circle control without dropping it. The Circle changes from blue to green. 








8. Drag the text away from the Circle control. The Circle changes from green back to blue. 

Enable a Panel to Receive Dropped Data 

In this section, you enable the panels that host the Circle user controls to act as drop targets for dragged Circle 

data. You will implement code that enables you to move a Circle from one panel to another, or to make a copy of a 

Circle control by holding down the Ctrl key while dragging and dropping a Circle. 

1. Open MainWindow.xaml. 

2. As shown in the following XAML, in each of the StackPanel controls, add handlers for the DragOver and 
Drop events. Name the DragOver event handler, panei_DragOven , and name the Drop event handler, 

panel_Dr'op . 

<StackPanel Gr'id.Column="0" 

Bacl<gr'ound=" Beige" 

AllowDrop="True" 

Dr'agOver'="panel_Dr'agOver'" 

Dr'op=" panel_Dr'op" > 

<TextBox Width="Auto" Margin="2" 

Text="green"/> 

<localrCincle Margin="2" /> 

<localrCincle Margin="2" /> 

</StackPanel> 

<StackPanel Gr'id.Column="l" 

Backgr'ound=" Bisque" 

AllowDrop="True" 

Dr'agOver="panel_Dr'agOver" 

Dr'op=" panel_Dr'op" > 

</StackPanel> 


3. Open MainWindows.xaml.es or MainWindow.xaml.vb. 

4. Add the following code for the DragOver event handler. 












private void panel_DragOver(object sender, DragEventArgs e) 

{ 

if (e.Data.GetDataPresent("Object")) 

{ 

// These Effects values are used in the drag source's 
// GiveFeedback event handler to determine which cursor to display, 
if (e.KeyStates == DragDropKeyStates.ControlKey) 

{ 

e.Effects = DragDropEffects.Copyj 

} 

else 

{ 

e.Effects = DragDropEffects.Move; 

} 

} 

} 


Private Sub panel_DragOver(ByVal sender As System.Object, ByVal e As System.Windows.DragEventArgs) 
If e.Data.GetDataPresent("Object") Then 

' These Effects values are used in the drag source's 
' GiveFeedback event handler to determine which cursor to display. 

If e.KeyStates = DragDropKeyStates.ControlKey Then 
e.Effects = DragDropEffects.Copy 

Else 

e.Effects = DragDropEffects.Move 
End If 
End If 
End Sub 


This DragOver event handler performs the following tasks: 

• Checks that the dragged data contains the "Object" data that was packaged in the DataObJect by the 
Circle user control and passed in the call to DoDragDrop. 

• If the "Object" data is present, checks whether the Ctrl key is pressed. 

• If the Ctrl key is pressed, sets the Effects property to Copy. Otherwise, set the Effects property to 
Move. 


5. Add the following code for the Drop event handler. 



private void panel_Drop(object sender^ DragEventArgs e) 

{ 

// If an element in the panel has already handled the drop^ 

// the panel should not also handle it. 
if (e.Handled == false) 

{ 

Panel _panel = (Panel)sender; 

UIElement _element = (LIIElement)e.Data.GetData("Object")j 

if (_panel != null && _element != null) 

{ 

// Get the panel that the element currently belongs tOj 
// then remove it from that panel and add it the Children of 
// the panel that its been dropped on. 

Panel _parent = (Panel)VisualTreeHelper.GetParent(_element); 

if (_parent != null) 

{ 

if (e.KeyStates == DragDropKeyStates.ControlKey && 
e.AllowedEffects.HasFlag(DragDropEffeets.Copy)) 

{ 

Circle _circle = new Circle((Circle)_element); 
_panel.Children.Add(_circle)j 

// set the value to return to the DoDragDrop call 
e.Effects = DragDropEffects.Copyj 

} 

else if (e.AllowedEffects.HasFlag(DragDropEffects.Move)) 

{ 

_parent.Children.Remove(_element); 

_panel.Children.Add(_element); 

// set the value to return to the DoDragDrop call 
e.Effects = DragDropEffects.Move; 

} 

} 

} 

} 

} 



Private Sub panel_Drop(ByVal sender As System.Objectj ByVal e As System.Windows.DragEventArgs) 
' If an element in the panel has already handled the drop, 

' the panel should not also handle it. 

If e.Handled = False Then 

Dim _panel As Panel = sender 

Dim _element As UIElement = e.Data.GetData("Object") 

If _panel IsNot Nothing And _element IsNot Nothing Then 
' Get the panel that the element currently belongs to, 

' then remove it from that panel and add it the Children of 
' the panel that its been dropped on. 

Dim _parent As Panel = VisualTreeHelper.GetParent(_element) 

If _parent IsNot Nothing Then 

If e.KeyStates = DragDropKeyStates.ControlKey And _ 

e.AllowedEffects.HasFlag(DragDropEffeets.Copy) Then 
Dim _circle As New Circle(_element) 

_panel.Children.Add(_circle) 

' set the value to return to the DoDragDrop call 
e.Effects = DragDropEffects.Copy 
Elself e.AllowedEffects.HasFlag(DragDropEffects.Move) Then 
_pa rent.Child ren.Remove(_element) 

_panel.Children.Add(_element) 

' set the value to return to the DoDragDrop call 
e.Effects = DragDropEffects.Move 
End If 
End If 
End If 
End If 
End Sub 


This Drop event handler performs the following tasks: 

• Checks whether the Drop event has already been handled. For instance, if a Circle is dropped on 
another Circle which handles the Drop event, you do not want the panel that contains the Circle to 
also handle it. 

• If the Drop event is not handled, checks whether the Ctrl key is pressed. 

• If the Ctrl key is pressed when the Drop happens, makes a copy of the Circle control and add it to the 
Children collection of the StackPanel. 

• If the Ctrl key is not pressed, moves the Circle from the Children collection of its parent panel to the 
Children collection of the panel that it was dropped on. 

• Sets the Effects property to notify the DoDragDrop method whether a move or copy operation was 
performed. 

6. Press F5 to build and run the application. 

7. Select the text green from the TextBox. 

8. Drag the text over a Circle control and drop it. 

9. Drag a Circle control from the left panel to the right panel and drop it. The Circle is removed from the 

Children collection of the left panel and added to the Children collection of the right panel. 

10. Drag a Circle control from the panel it is in to the other panel and drop it while pressing the Ctrl key. The 

Circle is copied and the copy is added to the Children collection of the receiving panel. 





See also 

• Drag and Drop Overview 










Drag and Drop How-to Topics 
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The following examples demonstrate how to accomplish common tasks using the Windows Presentation 
Foundation (WPF) drag-and-drop framework. 

In This Section 

Open a File That is Dropped on a RichTextBox Control 
Create a Data Object 

Determine if a Data Format is Present in a Data Object 
List the Data Formats in a Data Object 
Retrieve Data in a Particular Data Format 
Store Multiple Data Formats in a Data Object 

See also 

• Drag and Drop Overview 




How to: Open a File That is Dropped on a 
RichTextBox Control 
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In Windows Presentation Foundation (WPF), the TextBox, RichTextBox, and FlowDocument controls all have built-in 
drag-and-drop functionality. The built-in functionality enables drag-and-drop of text within and between the 
controls. However, it does not enable opening a file by dropping the file on the control. These controls also mark 
the drag-and-drop events as handled. As a result, by default, you cannot add your own event handlers to provide 
functionality to open dropped files. 

To add additional handling for drag-and-drop events in these controls, use the AddHandler(RoutedEvent, Delegate, 
Boolean) method to add your event handlers for the drag-and-drop events. Set the handiedEventsToo parameter to 
true to have the specified handler be invoked for a routed event that has already been marked as handled by 
another element along the event route. 


TIP 

You can replace the built-in drag-and-drop functionality of TextBox, RichTextBox, and FlowDocument by handling the preview 
versions of the drag-and-drop events and marking the preview events as handled. However, this will disable the built-in 
drag-and-drop functionality, and is not recommended. 


Example 

The following example demonstrates how to add handlers for the DragOver and Drop events on a RichTextBox. This 
example uses the AddHandler(RoutedEvent, Delegate, Boolean) method and sets the handiedEventsToo parameter 
to true so that the events handlers will be invoked even though the RichTextBox marks these events as handled. 
The code in the event handlers adds functionality to open a text file that is dropped on the RichTextBox. 

To test this example, drag a text file or a rich text format (RTF) file from Windows Explorer to the RichTextBox. The 
file will be opened in the RichTextBox. If you press the SHIFT key before the dropping the file, the file will be opened 
as plain text. 

<RichTextBox x:Mame="richTextBoxl" 

AllowDnop="Tnue" /> 










public MainWindowO 

{ 

InitializeComponent(); 

// Add using System.Windows.Controls; 

richTextBoxl.AddHandler(RichTextBox.DragOverEvent, new DragEventHandler(RichTextBox_DragOver), true) 
rlchTextBoxl.AddHandler(RichTextBox.DropEvent, new DragEventHandler(RichTextBox_Drop), true); 

} 

private void RichTextBox_DragOver(object sender, DragEventArgs e) 

{ 

if (e.Data.GetDataPresent(DataFormats.FileDrop)) 

{ 

e.Effects = DragDropEffects.All; 

} 

else 

{ 

e.Effects = DragDropEffects.None; 

} 

e.Flandled = false; 


private void RichTextBox_Drop(object sender, DragEventArgs e) 

{ 

if (e.Data.GetDataPresent(DataFormats.FileDrop)) 

{ 

string[] docPath = (string[])e.Data.GetData(DataFormats.FileDrop); 

// By default, open as Rich Text (RTF), 
var dataFormat = DataFormats.Rtf; 

// If the Shift key is pressed, open as plain text, 
if (e.KeyStates == DragDropKeyStates.ShiftKey) 

{ 

dataFormat = DataFormats.Text; 

} 

System.Windows.Documents.TextRange range; 

System.10.FileStream fStream; 
if (System. 10. File. Exists(docPath[0])) 

{ 

try 

{ 

// Open the document in the RichTextBox. 

range = new System.Windows.Documents.TextRange(richTextBoxl.Document.ContentStart, 
richTextBoxl.Document.ContentEnd); 

fStream = new System.10.FileStream(docPath[0], System.10.FileMode.OpenOrCreate); 
range.Load(fStream, dataFormat); 
fStream.CloseO; 

} 

catch (System.Exception) 

{ 

MessageBox.Show("File could not be opened. Make sure the file is a text file."); 

} 



Public Sub IMew() 

InitializeComponent() 

rlchTextBoxl.AddHandler(RichTextBox.DnagOverEventj New DragEventHandler(AddressOf RichTextBox_DragOver), 
True) 

richTextBoxl.AddHandler(RichTextBox.DropEvent, New DnagEventElandler(AddressOf RichTextBox_Drop)^ True) 
End Sub 

Private Sub RichTextBox_DragOver(sender As Object, e As DragEventArgs) 

If e.Data.GetDataPresent(DataFormats.FileDrop) Then 
e.Effects = DragDropEffects.All 

Else 

e.Effects = DragDropEffects.None 
End If 

e.Handled = False 
End Sub 

Private Sub RichTextBox_Drop(sender As Object, e As DragEventArgs) 

If e.Data.GetDataPresent(DataFormats.FileDrop) Then 

Dim docPath As StringO = TryCast(e.Data.GetData(DataFormats.FileDrop), StringO) 

' By default, open as Rich Text (RTF). 

Dim dataFormat = DataFormats.Rtf 

' If the Shift key is pressed, open as plain text. 

If e.KeyStates = DragDropKeyStates.ShiftKey Then 
dataFormat = DataFormats.Text 
End If 

Dim range As TextRange 
Dim fStream As 10.FileStream 
If 10.File.Exists(docPath(0)) Then 
Try 

' Open the document in the RichTextBox. 

range = New TextRange(richTextBoxl.Document.ContentStart, richTextBoxl.Document.ContentEnd) 
fStream = New IO.FileStream(docPath(0), lO.FileMode.OpenOrCreate) 
range.Load(fStream, dataFormat) 
fStream.CloseO 

Catch generatedExceptionName As System.Exception 

MessageBox.Show("File could not be opened. Make sure the file is a text file.") 

End Try 
End If 
End If 
End Sub 



How to: Create a Data Object 
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The following examples show various ways to create a data object using the constructors provided by the 
DataObject class. 

Example 

Description 

The following example code creates a new data object and uses one of the overloaded constructors 
(DataObject(Object)) to initialize the data object with a string. In this case, an appropriate data format is determined 
automatically according to the stored data's type, and auto-converting of the stored data is allowed by default. 

Code 

string stringData = "Some string data to store..."; 

DataObject dataObject = new DataObject(stringData); 


Dim StringData As String = "Some string data to store..." 

Dim dataObject As New DataObject(stringData) 

Description 

The following example code is a condensed version of the code shown above. 

Code 

DataObject dataObject = new DataObject("Some string data to store..."); 

Dim dataObject As New DataObject("Some string data to store...") 


Example 

Description 

The following example code creates a new data object and uses one of the overloaded constructors 
(DataObjectfString, Object)) to initialize the data object with a string and a specified data format. In this case the 
data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. Auto¬ 
converting of the stored data is allowed by default. 

Code 

string StringData = "Some string data to store..."; 
string dataFormat = DataFormats.UnicodeText; 

DataObject dataObject = new DataObject(dataFormat, stringData); 







Dim stringData As String = "Some string data to store..." 

Dim dataFormat As String = DataFormats.UnicodeText 

Dim dataObject As New DataObject(dataFormatj stringData) 


Description 

The following example code is a condensed version of the code shown above. 

Code 

DataObject dataObject = new DataObject(DataFormats.LlnicodeTextj "Some string data to store..."); 

Dim dataObject As New DataObject(DataFormats.LlnicodeTextj "Some string data to store...") 


Example 

Description 

The following example code creates a new data object and uses one of the overloaded constructors (DataObject) to 
initialize the data object with a string and a specified data format. In this case the data format is specified by a Type 
parameter. Auto-converting of the stored data is allowed by default. 

Code 

string StringData = "Some string data to store..."; 

Type dataFormat = stringData.GetType(); 

DataObject dataObject = new DataObject(dataFormat, stringData); 


Dim StringData As String = "Some string data to store..." 
Dim dataFormat As Type = stringData.GetType() 

Dim dataObject As New DataObject(dataFormatj stringData) 


Description 

The following example code is a condensed version of the code shown above. 

Code 

DataObject dataObject = new DataObject("" .GetTypeO, "Some string data to store..."); 

Dim dataObject As New DataObject("".GetType(), "Some string data to store...") 


Example 

Description 

The following example code creates a new data object and uses one of the overloaded constructors 
(DataObject(String, Object, Boolean)) to initialize the data object with a string and a specified data format. In this 
case the data format is specified by a string; the DataFormats class provides a set of pre-defined type strings. This 
particular constructor overload enables the caller to specify whether auto-converting is allowed. 


Code 





string stringData = "Some string data to store..."j 
string dataFormat = DataFormats.Text; 
bool autoConvert = false; 

DataObject dataObject = new DataObject(dataFormatj stringData, autoConvert); 


Dim StringData As String = "Some string data to store..." 

Dim dataFormat As String = DataFormats.Text 
Dim autoConvert As Boolean = False 

Dim dataObject As New DataObject(dataFormat, stringData, autoConvert) 


Description 

The following example code is a condensed version of the code shown above. 

Code 

DataObject dataObject = new DataObject(DataFormats.Text, "Some string data to store...", false); 


Dim dataObject As New DataObject(DataFormats.Text, "Some string data to store...". False) 


See also 

• IDataObject 




How to: Determine if a Data Format is Present in a 
Data Object 
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The following examples show how to use the various GetDataPresent method overloads to query whether a 
particular data format is present in a data object. 

Example 

Description 

The following example code uses the GetDataPresent(String) overload to query for the presence of a particular 
data format by descriptor string. 

Code 

DataObject dataObject = new DataObject("Some string data to store...")j 

// Query for the presence of Text data in the data object, by a data format descriptor string. 

// In this overload of GetDataPresent, the method will return true both for native data formats 
// and when the data can automatically be converted to the specifed format. 

// In this case, string data is present natively, so GetDataPresent returns "true", 
string textData = null; 

if (dataObject.GetDataPresent(DataFormats.StringPormat)) 

{ 

textData = dataObject.GetData(DataFormats.StringFormat) as string; 

} 

// In this case, the Text data in the data object can be autoconverted to 
// Unicode text, so GetDataPresent returns "true". 
byte[] unicodeData = null; 

if (dataObject.GetDataPresent(DataFormats.Unicode!ext)) 

{ 

unicodeData = dataObject.GetData(DataFormats.UnicodeText) as byte[]; 

} 


Dim dataObject As New DataObject("Some string data to store...") 

' Query for the presence of Text data in the data object, by a data format descriptor string. 

' In this overload of GetDataPresent, the method will return true both for native data formats 
' and when the data can automatically be converted to the specifed format. 

' In this case, string data is present natively, so GetDataPresent returns "true". 

Dim textData As String = Nothing 

If dataObject.GetDataPresent(DataFormats.StringFormat) Then 

textData = TryCast(dataObject.GetData(DataFormats.StringFormat), String) 

End If 

' In this case, the Text data in the data object can be autoconverted to 
' Unicode text, so GetDataPresent returns "true". 

Dim unicodeData() As Byte = Nothing 

If dataObject.GetDataPresent(DataFormats.UnicodeText) Then 

unicodeData = TryCast(dataObject.GetData(DataFormats.UnicodeText), Byte()) 

End If 





Example 

Description 

The following example code uses the GetDataPresent(Type) overload to query for the presence of a particular data 
format by type. 

Code 

DataObject dataObject = new DataObject("Some string data to store...")j 

// Query for the presence of String data in the data object, by type. In this overload 
// of GetDataPresent, the method will return true both for native data formats 
// and when the data can automatically be converted to the specifed format. 

// In this case, the Text data present in the data object can be autoconverted 

// to type string (also represented by DataFormats.String), so GetDataPresent returns "true". 

string stringData = null; 

if (dataObject.GetDataPresent(typeof(String))) 

{ 

StringData = dataObject.GetData(DataFormats.Text) as string; 

} 


Dim dataObject As New DataObject("Some string data to store...") 

' Query for the presence of String data in the data object, by type. In this overload 
' of GetDataPresent, the method will return true both for native data formats 
' and when the data can automatically be converted to the specifed format. 

' In this case, the Text data present in the data object can be autoconverted 

' to type string (also represented by DataFormats.String), so GetDataPresent returns "true". 

Dim StringData As String = Nothing 

If dataObject.GetDataPresent(GetType(String)) Then 

StringData = TryCast(dataObject.GetData(DataFormats.Text), String) 

End If 


Example 

Description 

The following example code uses the GetDataPresent(String, Boolean) overload to query for data by descriptor 
string, and specifying how to treat auto-convertible data formats. 


Code 



DataObject dataObject = new DataObject("Some string data to store...")j 

// Query for the presence of Text data in the data object, by data format descriptor string, 
// and specifying whether auto-convertible data formats are acceptable. 

// In this case. Text data is present natively, so GetDataPresent returns "true", 
string textData = null; 

if (dataObject.GetDataPresent(DataFormats.Text, false /* Auto-convert? */)) 

{ 

textData = dataObject.GetData(DataFormats.Text) as string; 

} 

// In this case, the Text data in the data object can be autoconverted to 

// Unicode text, but it is not available natively, so GetDataPresent returns "false". 

byte[] unicodeData = null; 

if (dataObject.GetDataPresent(DataFormats.UnicodeText, false /* Auto-convert? */)) 

{ 

unicodeData = dataObject.GetData(DataFormats.UnicodeText) as byte[]; 

} 

// In this case, the Text data in the data object can be autoconverted to 
// Unicode text, so GetDataPresent returns "true". 

if (dataObject.GetDataPresent(DataFormats.UnicodeText, true /* Auto-convert? */)) 

{ 

unicodeData = dataObject.GetData(DataFormats.UnicodeText) as byte[]; 

} 


Dim dataObject As New DataObject("Some string data to store...") 

' Query for the presence of Text data in the data object, by data format descriptor string, 
' and specifying whether auto-convertible data formats are acceptable. 

' In this case. Text data is present natively, so GetDataPresent returns "true". 

Dim textData As String = Nothing 

If dataObject.GetDataPresent(DataFormats.Text, False) Then ' Auto-convert? 

textData = TryCast(dataObject.GetData(DataFormats.Text), String) 

End If 

' In this case, the Text data in the data object can be autoconverted to 
' Unicode text, but it is not available natively, so GetDataPresent returns "false". 

Dim unicodeData() As Byte = Nothing 

If dataObject.GetDataPresent(DataFormats.UnicodeText, False) Then ' Auto-convert? 

unicodeData = TryCast(dataObject.GetData(DataFormats.UnicodeText), Byte()) 

End If 

' In this case, the Text data in the data object can be autoconverted to 
' Unicode text, so GetDataPresent returns "true". 

If dataObject.GetDataPresent(DataFormats.UnicodeText, True) Then ' Auto-convert? 

unicodeData = TryCast(dataObject.GetData(DataFormats.UnicodeText), Byte()) 

End If 


See also 


• IDataObject 



How to: List the Data Formats in a Data Object 
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The following examples show how to use the GetFormats method overloads get an array of strings denoting each 
data format that is available in a data object. 

Example 

Description 

The following example code uses the GetFormats overload to get an array of strings denoting all data formats 
available in a data object (both native and auto-convertible). 

Code 

DataObject dataObject = new DataObject("Some string data to store...")j 

// Get an array of strings^ each string denoting a data format 
// that is available in the data object. This overload of GetDataFormats 
// returns all available data formats^ native and auto-convertible. 
string[] dataFormats = dataObject.GetFormats()j 

// Get the number of data formats present in the data object^ including both 
// auto-convertible and native data formats, 
int numberOfDataFormats = dataFormats.Length; 

// To enumerate the resulting array of data formats, and take some action when 

// a particular data format is found, use a code structure similar to the following. 

foreach (string dataFormat in dataFormats) 

{ 

if (dataFormat == DataFormats.Text) 

{ 

// Take some action if/when data in the Text data format is found, 
break; 

} 

else if(dataFormat == DataFormats.StringFormat) 

{ 

// Take some action if/when data in the string data format is found, 
break; 

} 

} 





Dim dataObject As New DataObject("Some string data to store...") 

' Get an array of strings^ each string denoting a data format 
' that is available in the data object. This overload of GetDataFormats 
' returns all available data formats^ native and auto-convertible. 

Dim dataFormats() As String = dataObject.GetFormats() 

' Get the number of data formats present in the data object, including both 
' auto-convertible and native data formats. 

Dim numberOfDataFormats As Integer = dataFormats.Length 

' To enumerate the resulting array of data formats, and take some action when 
' a particular data format is found, use a code structure similar to the following. 
For Each dataFormat As String In dataFormats 

If dataFormat = System.Windows.DataFormats.Text Then 

' Take some action if/when data in the Text data format is found. 

Exit For 

Elself dataFormat = System.Windows.DataFormats.StringFormat Then 

' Take some action if/when data in the string data format is found. 

Exit For 
End If 

Next dataFormat 


Example 

Description 

The following example code uses the GetFormats overload to get an array of strings denoting only data formats 
available in a data object (auto-convertible data formats are filtered). 

Code 

DataObject dataObject = new DataObject("Some string data to store...")j 

// Get an array of strings, each string denoting a data format 
// that is available in the data object. This overload of GetDataFormats 
// accepts a Boolean parameter inidcating whether to include auto-convertible 
// data formats, or only return native data formats. 

string[] dataFormats = dataObject.GetFormats(false /* Include auto-convertible? */); 

// Get the number of native data formats present in the data object, 
int numberOfDataFormats = dataFormats.Length; 

// To enumerate the resulting array of data formats, and take some action when 

// a particular data format is found, use a code structure similar to the following. 

foreach (string dataFormat in dataFormats) 

{ 

if (dataFormat == DataFormats.Text) 

{ 

// Take some action if/when data in the Text data format is found, 
break; 

} 

} 




Dim dataObject As New DataObject("Some string data to store...") 


' Get an array of strings^ each string denoting a data format 
' that is available in the data object. This overload of GetDataFormats 
' accepts a Boolean parameter inidcating whether to include auto-convertible 
' data formatsj or only return native data formats. 

Dim dataFormatsO As String = dataObject.GetFormats(False) ' Include auto-convertible 

' Get the number of native data formats present in the data object. 

Dim numberOfDataFormats As Integer = dataFormats.Length 

' To enumerate the resulting array of data formats^ and take some action when 
' a particular data format is founds use a code structure similar to the following. 
For Each dataFormat As String In dataFormats 

If dataFormat = System.Windows.DataFormats.Text Then 

' Take some action if/when data in the Text data format is found. 

Exit For 
End If 

Next dataFormat 


See also 

• IDataObject 

• Drag and Drop Overview 
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The following examples show how to retrieve data from a data object in a specified format. 

Example 

Description 

The following example code uses the GetDataPresent(String) overload to first check if a specified data format is 
available (natively or by auto-convert); if the specified format is available, the example retrieves the data by using 
the GetData(String) method. 

Code 

DataObject dataObject = new DataObject("Some string data to store...")j 

string desiredFormat = DataFormats.UnicodeText; 
byte[] data = null; 

// Use the GetDataPresent method to check for the presence of a desired data format. 

// This particular overload of GetDataPresent looks for both native and auto-convertible 
// data formats. 

if (dataObject.GetDataPresent(desiredFormat)) 

{ 

// If the desired data format is present^ use one of the GetData methods to retrieve the 
// data from the data object. 

data = dataObject.GetData(desiredFormat) as byte[]; 

} 


Dim dataObject As New DataObject("Some string data to store...") 

Dim desiredFormat As String = DataFormats.UnicodeText 
Dim data() As Byte = Nothing 

' Use the GetDataPresent method to check for the presence of a desired data format. 

' This particular overload of GetDataPresent looks for both native and auto-convertible 
' data formats. 

If dataObject.GetDataPresent(desiredFormat) Then 

' If the desired data format is present, use one of the GetData methods to retrieve the 
' data from the data object. 

data = TryCast(dataObject.GetData(desiredFormat), Byte()) 

End If 


Example 

Description 

The following example code uses the GetDataPresent(String, Boolean) overload to first check if a specified data 
format is available natively (auto-convertible data formats are filtered); if the specified format is available, the 
example retrieves the data by using the GetData(String) method. 


Code 





DataObject dataObject = new DataObject("Some string data to store...")j 

string desiredFormat = DataFormats.UnicodeTextj 
bool noAutoConvert = false; 
byte[] data = null; 

// Use the GetDataPresent method to check for the presence of a desired data format. 

// The autoconvert parameter is set to false to filter out auto-convertible data formats^ 

// returning true only if the specified data format is available natively, 
if (dataObject.GetDataPresent(desiredFormat, noAutoConvert)) 

{ 

// If the desired data format is present^ use one of the GetData methods to retrieve the 
// data from the data object. 

data = dataObject.GetData(desiredFormat) as byte[]; 

} 


Dim dataObject As New DataObject("Some string data to store...") 

Dim desiredFormat As String = DataFormats.UnicodeText 
Dim noAutoConvert As Boolean = False 
Dim data() As Byte = Nothing 

' Use the GetDataPresent method to check for the presence of a desired data format. 

' The autoconvert parameter is set to false to filter out auto-convertible data formats, 

' returning true only if the specified data format is available natively. 

If dataObject.GetDataPresent(desiredFormat, noAutoConvert) Then 

' If the desired data format is present, use one of the GetData methods to retrieve the 
' data from the data object. 

data = TryCast(dataObject.GetData(desiredFormat), Byte()) 

End If 


See also 


• IDataObject 

• Drag and Drop Overview 
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The following example shows how to use the SetData(String, Object) method to add data to a data object in 
multiple formats. 

Example 

Description 

Code 

DataObject dataObject = new DataObject(); 

string sourceData = "Some string data to store..."j 

// Encode the source string into Unicode byte arrays. 
byte[] unicodeText = Encoding.Unicode.GetBytes(sourceData)j // UTF-16 
byte[] utfSText = Encoding.UTF8.GetBytes(sourceData); 
byte[] utf32Text = Encoding.UTF32.GetBytes(sourceData)j 

// The DataFormats class does not provide data format fields for denoting 
// UTF-32 and UTF-8j which are seldom used in practice; the following strings 
// will be used to identify these "custom" data formats, 
string utf32DataFormat = "UTF-32"; 
string utf8DataFormat = "UTF-8"; 

// Store the text in the data object^ letting the data object choose 
// the data format (which will be DataFormats.Text in this case). 
dataObj ect.SetData(sourceData); 

// Store the Unicode text in the data object. Text data can be automatically 
// converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 

// Therefore^ explicitly converting the source text to Unicode is generally unnecessary, and 
// is done here as an exercise only. 

dataObject.SetData(DataFormats.UnicodeText, unicodeText); 

// Store the UTF-8 text in the data object... 
dataObj ect.SetData(utf8DataFormat, utf8Text); 

// Store the UTF-32 text in the data object... 
dataObj ect.SetData(utf32DataFormat, utf32Text); 





Dim dataObject As New DataObject() 

Dim sounceData As String = "Some string data to store..." 

' Encode the source string into Unicode byte arrays. 

Dim unicodeTextO As Byte = Encoding.Unicode.GetBytes(sourceData) ' UTF-16 
Dim utfSTextO As Byte = Encoding.UTF8.GetBytes(sourceData) 

Dim utf32Text() As Byte = Encoding.UTF32.GetBytes(sourceData) 

' The DataFormats class does not provide data format fields for denoting 
' UTF-32 and UTF-8, which are seldom used in practice; the following strings 
' will be used to identify these "custom" data formats. 

Dim utf32DataFormat As String = "UTF-32" 

Dim utf8DataFormat As String = "UTF-8" 

' Store the text in the data object^ letting the data object choose 
' the data format (which will be DataFormats.Text in this case). 
dataObject.SetData(sourceData) 

' Store the Unicode text in the data object. Text data can be automatically 
' converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 

' Thereforej explicitly converting the source text to Unicode is generally unnecessary^ and 
' is done here as an exercise only. 

dataObject.SetData(DataFormats.UnicodeTextj unicodeText) 

' Store the UTF-8 text in the data object... 
dataObject.SetData(utf8DataFormatj utf8Text) 

' Store the UTF-32 text in the data object... 
dataObj ect.SetData(utf32DataFormat ^ utf32Text) 


See also 


• IDataObject 

• Drag and Drop Overview 
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A resource is an object that can be reused in different places in your application. WPF supports different types of 
resources. These resources are primarily two types of resources: XAML resources and resource data files. 
Examples of XAML resources include brushes and styles. Resource data files are non-executable data files that an 
application needs. 

In This Section 

XAML Resources 

WPF Application Resource, Content, and Data Files 
PackURIs in WPF 

Reference 

ResourceDictionary 
StaticResource Markup Extension 
DynamicResource Markup Extension 
x:Key Directive 

Related Sections 


XAML in WPF 
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A resource is an object that can be reused in different places in your app. Examples of resources include 
brushes and styles. This overview describes how to use resources in Extensible Application Markup Language 
(XAML). You can also create and access resources by using code. 



Using resources in XAML 

The following example defines a SolidColorBrush as a resource on the root element of a page. The example 
then references the resource and uses it to set properties of several child elements, including an Ellipse, a 
TextBlock, and a Button. 







<Page Name="r'oot" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

<Page.Resources> 

tSolidColorBnush x:Key="MyBrush" Colon="Gold"/> 

<Style TargetType="Border'" x:Key="PageBackground"> 
tSetten Property="Background" Value="Blue"/> 

</Style> 

<Style TargetType="TextBlock" x:Key="TitleText"> 
tSetten Property="Background" Value="Blue"/> 
tSetten Property="DockPanel.Dock" Value="Top"/> 
cSetten Property="FontSize" Value="18"/> 
cSetten Property="Foreground" Value="#4E87D4"/> 
tSetten Property="FontFamily" Value="Trebuchet MS"/> 
tSetten Property="Mar'gin" Value="0j40jl0jl0"/> 

</Style> 

<Style TargetType="TextBlock" x:Key="Label"> 

cSetten Property="DockPanel.Dock" Value="Right"/> 
tSetten Property="FontSize" Value="8"/> 

tSetten Property="For'eground" Value="{StaticResource MyBrush}"/> 
cSetten Property="FontFamily" Value="Arial"/> 
cSetten Property="FontWeight" Value="Bold"/> 
tSetten Property="Mar'gin" Value="0j3,10j0"/> 

</Style> 

</Page.Resources> 

<StackPanel> 

cBorden Style="{StaticResource PageBackground}"> 

<DockPanel> 

<TextBlock Style="{StaticResource TitleText}">Title</TextBlock> 

<TextBlock Style="{StaticResource Label}">Label</TextBlock> 

<TextBlock DockPanel.Dock="Top" FlorizontalAlignment="Left" FontSize="36" Foreground=" 
{StaticResounce MyBrush}" Text="Text" Margin="20" /> 

<Button DockPanel.Dock="Top" FlorizontalAlignment="Left" Fleight="30" Background="{StaticResource 
MyBrush}" Margin="40">Button</Button> 

<Ellipse DockPanel.Dock="Top" FlorizontalAlignment="Left" Width="100" Fleight="100" Fill=" 
{StaticResounce MyBrush}" Margin="40" /> 

</DockPanel> 

</Border> 

</StackPanel> 

</Page> 


Every framework-level element (FrameworkElement or FrameworkContentElement) has a Resources property, 
which is a ResourceDictionary type that contains defined resources. You can define resources on any element, 
such as a Button. However, resources are most often defined on the root element, which is Page in the 
example. 

Each resource in a resource dictionary must have a unique key. When you define resources in markup, you 
assign the unique key through the x:Key Directive. Typically, the key is a string; however, you can also set it to 
other object types by using the appropriate markup extensions. Non-string keys for resources are used by 
certain feature areas in WPF, notably for styles, component resources, and data styling. 

You can use a defined resource with the resource markup extension syntax that specifies the key name of the 
resource. For example, use the resource as the value of a property on another element. 

<Button Background^'TStaticResounce MyBrush}"/> 

<Ellipse Fill="{StaticResource MyBr'ush}"/> 

In the preceding example, when the XAML loader processes the value {staticResource MyBrush} for the 
Background property on Button, the resource lookup logic first checks the resource dictionary for the Button 





element. If Button doesn't have a definition of the resource key MyBrush (in that example it doesn't; its 
resource collection is empty), the lookup next checks the parent element of Button, which is Page. If you define 
a resource on the Page root element, all the elements in the logical tree of the Page can access it. And you can 
reuse the same resource for setting the value of any property that accepts the same type that the resource 
represents. In the previous example, the same MyBrush resource sets two different properties: the Background 
of a Button, and the Fill of a Rectangle. 

Static and dynamic resources 

A resource can be referenced as either static or dynamic. References are created by using either the 
StaticResource Markup Extension or the DynamicResource Markup Extension. A markup extension is a XAML 
feature that lets you specify an object reference by having the markup extension process the attribute string 
and return the object to a XAML loader. For more information about markup extension behavior, see Markup 
Extensions and WPF XAML. 

When you use a markup extension, you typically provide one or more parameters in string form that are 
processed by that particular markup extension. The StaticResource Markup Extension processes a key by 
looking up the value for that key in all available resource dictionaries. Processing happens during load, which 
is when the loading process needs to assign the property value. The DynamicResource Markup Extension 
instead processes a key by creating an expression, and that expression remains unevaluated until the app 
runs, at which time the expression is evaluated and provides a value. 

When you reference a resource, the following considerations can influence whether you use a static resource 
reference or a dynamic resource reference: 

• When determining the overall design of how you create the resources for your app (per page, in the 
app, in loose XAML, or in a resource-only assembly), consider the following: 

• The app's functionality. Are updating resources in real-time part of your app requirements? 

• The respective lookup behavior of that resource reference type. 

• The particular property or resource type, and the native behavior of those types. 

Static resources 

Static resource references work best for the following circumstances: 

• Your app design concentrates most of its resources into page or application-level resource dictionaries. 
Static resource references aren't reevaluated based on runtime behaviors, such as reloading a page. So 
there can be some performance benefit to avoiding large numbers of dynamic resource references 
when they aren't necessary based on your resource and app design. 

• You're setting the value of a property that isn't on a DependencyObject or a Freezable. 

• You're creating a resource dictionary that will be compiled into a DLL and packaged as part of the app 
or shared between apps. 

• You're creating a theme for a custom control and are defining resources that are used within the 
themes. For this case, you typically do not want the dynamic resource reference lookup behavior; you 
instead want the static resource reference behavior so that the lookup is predictable and self-contained 
to the theme. With a dynamic resource reference, even a reference within a theme is left unevaluated 
until run-time, and there is a chance that when the theme is applied, some local element will redefine a 
key that your theme is trying to reference, and the local element will fall prior to the theme itself in the 
lookup. If that happens, your theme will not behave as expected. 

• You're using resources to set large numbers of dependency properties. Dependency properties have 




effective value caching as enabled by the property system, so if you provide a value for a dependency 
property that can be evaluated at load time, the dependency property doesn't have to check for a 
reevaluated expression and can return the last effective value. This technique can be a performance 
benefit. 

• You want to change the underlying resource for all consumers, or you want to maintain separate 
writable instances for each consumer by using the xiShared Attribute. 

Static resource lookup behavior 

The following describes the lookup process that automatically happens when a static resource is referenced 
by a property or element: 

1. The lookup process checks for the requested key within the resource dictionary defined by the element 
that sets the property. 

2. The lookup process then traverses the logical tree upward to the parent element and its resource 
dictionary. This process continues until the root element is reached. 

3. App resources are checked. App resources are those resources within the resource dictionary that is 
defined by the Application object for your WPF app. 

Static resource references from within a resource dictionary must reference a resource that has already been 
defined lexically before the resource reference. Forward references cannot be resolved by a static resource 
reference. For this reason, design your resource dictionary structure such that resources are defined at or near 
the beginning of each respective resource dictionary. 

Static resource lookup can extend into themes or into system resources, but this lookup is supported only 
because the XAML loader defers the request. The deferral is necessary so that the runtime theme at the time 
the page loads applies properly to the app. However, static resource references to keys that are known to only 
exist in themes or as system resources aren't recommended, because such references aren't reevaluated if the 
theme is changed by the user in real time. A dynamic resource reference is more reliable when you request 
theme or system resources. The exception is when a theme element itself requests another resource. These 
references should be static resource references, for the reasons mentioned earlier. 

The exception behavior if a static resource reference isn't found varies. If the resource was deferred, then the 
exception occurs at runtime. If the resource was not deferred, the exception occurs at load time. 

Dynamic resources 

Dynamic resources work best when: 

• The value of the resource, including system resources, or resources that are otherwise user settable, 
depends on conditions that aren't known until runtime. For example, you can create setter values that 
refer to system properties as exposed by SystemColors, SystemFonts, or System Parameters. These 
values are truly dynamic because they ultimately come from the runtime environment of the user and 
operating system. You might also have application-level themes that can change, where page-level 
resource access must also capture the change. 

• You're creating or referencing theme styles for a custom control. 

• You intend to adjust the contents of a ResourceDictionary during an app lifetime. 

• You have a complicated resource structure that has interdependencies, where a forward reference may 
be required. Static resource references do not support forward references, but dynamic resource 
references do support them because the resource doesn't need to be evaluated until runtime, and 
forward references are therefore not a relevant concept. 

• You're referencing a resource that is large from the perspective of a compile or working set, and the 


resource might not be used immediately when the page loads. Static resource references always load 
from XAML when the page loads. However, a dynamic resource reference doesn't load until it's used. 

• You're creating a style where setter values might come from other values that are influenced by themes 
or other user settings. 

• You're applying resources to elements that might be reparented in the logical tree during app lifetime. 
Changing the parent also potentially changes the resource lookup scope, so if you want the resource 
for a reparented element to be reevaluated based on the new scope, always use a dynamic resource 
reference. 

Dynamic resource lookup behavior 

Resource lookup behavior for a dynamic resource reference parallels the lookup behavior in your code if you 

call FindResource or SetResourceReference; 

1. The lookup checks for the requested key within the resource dictionary defined by the element that 
sets the property: 

• If the element defines a Style property, the System.Windows.FrameworkElement.Style of the 
element has its Resources dictionary checked. 

• If the element defines a Template property, the System.Windows.FrameworkTemplate.Resources 
dictionary of the element is checked. 

2. The lookup traverses the logical tree upward to the parent element and its resource dictionary. This 
process continues until the root element is reached. 

3. App resources are checked. App resources are those resources within the resource dictionary that are 
defined by the Application object for your WPF app. 

4. The theme resource dictionary is checked for the currently active theme. If the theme changes at 
runtime, the value is reevaluated. 

5. System resources are checked. 

Exception behavior (if any) varies: 

• If a resource was requested by a FindResource call and was not found, an exception is thrown. 

• If a resource was requested by a TryFindResource call and was not found, no exception is thrown, and 
the returned value is null . If the property being set doesn't accept null , then it's still possible that a 
deeper exception will be thrown, depending on the individual property being set. 

• If a resource was requested by a dynamic resource reference in XAML and was not found, then the 
behavior depends on the general property system. The general behavior is as if no property setting 
operation occurred at the level where the resource exists. For instance, if you attempt to set the 
background on an individual button element using a resource that could not be evaluated, then no 
value set results, but the effective value can still come from other participants in the property system 
and value precedence. For instance, the background value might still come from a locally defined 
button style or from the theme style. For properties that aren't defined by theme styles, the effective 
value after a failed resource evaluation might come from the default value in the property metadata. 

Restrictions 

Dynamic resource references have some notable restrictions. At least one of the following conditions must be 

true: 

• The property being set must be a property on a FrameworkElement or FrameworkContentElement. 

That property must be backed by a DependencyProperty. 




• The reference is for a value within a styiesetter . 

• The property being set must be a property on a Freezable that is provided as a value of either a 
FrameworkElement or FrameworkContentElement property, or a Setter value. 

Because the property being set must be a DependencyProperty or Freezable property, most property changes 
can propagate to the Ul because a property change (the changed dynamic resource value) is acknowledged by 
the property system. Most controls include logic that will force another layout of a control if a 
DependencyProperty changes and that property might affect layout. However, not all properties that have a 
DynamicResource Markup Extension as their value are guaranteed to provide real time updates in the Ul. That 
functionality still might vary depending on the property, as well as depending on the type that owns the 
property, or even the logical structure of your app. 

Styles, DataTemplates, and implicit keys 

Although all items in a ResourceDictionary must have a key, that doesn't mean that all resources must have an 
explicit x:Key . Several object types support an implicit key when defined as a resource, where the key value is 
tied to the value of another property. This type of key is known as an implicit key, whereas an x:Key attribute 
is an explicit key. You can overwrite any implicit key by specifying an explicit key. 

One important scenario for resources is when you define a Style. In fact, a Style is almost always defined as an 
entry in a resource dictionary, because styles are inherently intended for reuse. For more information about 
styles, see Styling and Templating. 

Styles for controls can be both created with and referenced with an implicit key. The theme styles that define 
the default appearance of a control rely on this implicit key. From the standpoint of requesting it, the implicit 
key is the Type of the control itself From the standpoint of defining the resources, the implicit key is the 
TargetType of the style. Therefore, if you're creating themes for custom controls or creating styles that interact 
with existing theme styles, you do not need to specify an x:Key Directive for that Style. And if you want to use 
the themed styles, you do not need to specify any style at all. For instance, the following style definition works, 
even though the Style resource doesn't appear to have a key: 

<Style TargetType="Button"> 

<Setter' Property=:"Background"> 

<Setter.Value> 

<tineanGradientBrushx 

<GnadientStop Offset="0.0" Color="AliceBlue"/> 

<GnadientStop Offset="1.0" Color="Salmon"/> 

</LinearGradientBrush) 

</Setter.Value) 

</Setter) 

<Setter Property="FontSize" Value="18"/) 

</Style) 

That style really does have a key: the implicit key typeof(System.Windows.controls.Button) . In markup, you can 
specify a TargetType directly as the type name (or you can optionally use {x:Type...} to return a Type. 

Through the default theme style mechanisms used by WPF, that style is applied as the runtime style of a 
Button on the page, even though the Button itself doesn't attempt to specify its Style property or a specific 
resource reference to the style. Your style defined in the page is found earlier in the lookup sequence than the 
theme dictionary style, using the same key that the theme dictionary style has. You could Just specify 
<Button)Heiio</Button) anywhere in the page, and the Style you defined with TargetType of Button would 
apply to that button. If you want, you can still explicitly key the style with the same type value as TargetType 
for clarity in your markup, but that is optional. 

Implicit keys for styles do not apply on a control if OverridesDefaultStyle is true . (Also note that 









OverridesDefaultStyle might be set as part of native behavior for the control class, rather than explicitly on an 
instance of the control.) Also, in order to support implicit keys for derived class scenarios, the control must 
override DefaultStyleKey (all existing controls provided as part of WPF include this override). For more 
information about styles, themes, and control design, see Guidelines for Designing Stylable Controls. 

Data Template also has an implicit key. The implicit key for a DataTemplate is the DataType property value. 
DataType can also be specified as the name of the type rather than explicitly using {x:Type...}. For details, see 
Data Tern plating Overview. 

See also 

• ResourceDictionary 

• Application resources 

• Resources and code 

• Define and reference a resource 

• Application management overview 

• x:Type markup extension 

• StaticResource markup extension 

• DynamicResource markup extension 
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This overview concentrates on how Windows Presentation Foundation (WPF) resources can be accessed or 
created using code rather than Extensible Application Markup Language (XAML) syntax. For more information on 
general resource usage and resources from a XAML syntax perspective, see XAML Resources. 

Accessing Resources from Code 

The keys that identify resources if they are defined through XAML are also used to retrieve specific resources if you 
request the resource in code. The simplest way to retrieve a resource from code is to call either the FindResource 
or the TryFindResource method from framework-level objects in your application. The behavioral difference 
between these methods is what happens if the requested key is not found. FindResource raises an exception; 
TryFindResource will not raise an exception but returns null . Each method takes the resource key as an input 
parameter, and returns a loosely typed object. Typically, a resource key is a string, but there are occasional 
nonstring usages; see the Using Objects as Keys section for details. Typically you would cast the returned object to 
the type required by the property that you are setting when requesting the resource. The lookup logic for code 
resource resolution is the same as the dynamic resource reference XAML case. The search for resources starts 
from the calling element, then continues to successive parent elements in the logical tree. The lookup continues 
onwards into application resources, themes, and system resources if necessary. A code request for a resource will 
properly account for runtime changes in resource dictionaries that might have been made subsequent to that 
resource dictionary being loaded from XAML, and also for realtime system resource changes. 

The following is a brief code example that finds a resource by key and uses the returned value to set a property, 
implemented as a Click event handler. 

void SetBGByResource(object sender, RoutedEventArgs e) 

{ 

Button b = sender as Button; 

b.Background = (Brush)this.FindResource("RainbowBrush"); 

} 

Private Sub SetBGByResource(ByVal sender As Object, ByVal e As RoutedEventArgs) 

Dim b As Button = TryCast(sender, Button) 

b.Background = CType(Me.FindResource("RainbowBrush"), Brush) 

End Sub 

An alternative method for assigning a resource reference is SetResourceReference. This method takes two 
parameters: the key of the resource, and the identifier for a particular dependency property that is present on the 
element instance to which the resource value should be assigned. Functionally, this method is the same and has 
the advantage of not requiring any casting of return values. 

Still another way to access resources programmatically is to access the contents of the Resources property as a 
dictionary. Accessing the dictionary contained by this property is also how you can add new resources to existing 
collections, check to see if a given key name is already taken in the collection, and other dictionary/collection 
operations. If you are writing a WPF application entirely in code, you can also create the entire collection in code, 
assign keys to it, and then assign the finished collection to the Resources property of an established element. This 
will be described in the next section. 

You can index within any given Resources collection, using a specific key as the index, but you should be aware that 






accessing the resource in this way does not follow the normal runtime rules of resource resolution. You are only 
accessing that particular collection. Resource lookup will not be traversing the scope to the root or the application 
if no valid object was found at the requested key. However, this approach may have performance advantages in 
some cases precisely because the scope of the search for the key is more constrained. See the ResourceDictionary 
class for more details on how to work with the resource dictionary directly. 

Creating Resources with Code 

If you want to create an entire WPF application in code, you might also want to create any resources in that 
application in code. To achieve this, create a new ResourceDictionary instance, and then add all the resources to the 
dictionary using successive calls to ResourceDictionary.Add. Then, use the ResourceDictionary thus created to set 
the Resources property on an element that is present in a page scope, or the Application.Resources. You could also 
maintain the ResourceDictionary as a standalone object without adding it to an element. However, if you do this, 
you must access the resources within it by item key, as if it were a generic dictionary. A ResourceDictionary that is 
not attached to an element Resources property would not exist as part of the element tree and has no scope in a 
lookup sequence that can be used by FindResource and related methods. 

Using Objects as Keys 

Most resource usages will set the key of the resource to be a string. However, various WPF features deliberately do 
not use a string type to specify keys, instead this parameter is an object. The capability of having the resource be 
keyed by an object is used by the WPF style and theming support. The styles in themes which become the default 
style for an otherwise non-styled control are each keyed by the Type of the control that they should apply to. Being 
keyed by type provides a reliable lookup mechanism that works on default instances of each control type, and type 
can be detected by reflection and used for styling derived classes even though the derived type otherwise has no 
default style. You can specify a Type key for a resource defined in XAML by using the x:Type Markup Extension. 
Similar extensions exist for other nonstring key usages that support WPF features, such as 
ComponentResourceKey Markup Extension. 

See also 

• XAML Resources 

• Styling and Templating 
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Windows Presentation Foundation (WPF) resources support a merged resource dictionary feature. This feature 
provides a way to define the resources portion of a WPF application outside of the compiled XAML application. 
Resources can then be shared across applications and are also more conveniently isolated for localization. 

Introducing a Merged Resource Dictionary 

In markup, you use the following syntax to introduce a merged resource dictionary into a page: 

<Page.Resources> 

<ResourceDictionary> 

<ResourceDictionar'y .MergedDictionaries> 

<ResourceDictionar'y Sour'ce="myresour'cedictionary.xaml"/> 

<ResourceDictionary Source="myresourcedictionary2.xaml"/> 

</ResourceDictionary.MergedDictionaries> 

</ResourceDictionary> 

</Page.Resources> 


Note that the ResourceDictionary element does not have an x:Key Directive, which is generally required for all items 
in a resource collection. But another ResourceDictionary reference within the MergedDictionaries collection is a 
special case, reserved for this merged resource dictionary scenario. The ResourceDictionary that introduces a 
merged resource dictionary cannot have an x:Key Directive. Typically, each ResourceDictionary within the 
MergedDictionaries collection specifies a Source attribute. The value of Source should be a uniform resource 
identifier (URI) that resolves to the location of the resources file to be merged. The destination of that URI must be 
another XAML file, with ResourceDictionary as its root element. 


NOTE 

It is legal to define resources within a ResourceDictionary that is specified as a merged dictionary, either as an alternative to 
specifying Source, or in addition to whatever resources are included from the specified source. Flowever, this is not a common 
scenario; the main scenario for merged dictionaries is to merge resources from external file locations. If you want to specify 
resources within the markup for a page, you should typically define these in the main ResourceDictionary and not in the 
merged dictionaries. 


Merged Dictionary Behavior 

Resources in a merged dictionary occupy a location in the resource lookup scope that is just after the scope of the 
main resource dictionary they are merged into. Although a resource key must be unique within any individual 
dictionary, a key can exist multiple times in a set of merged dictionaries. In this case, the resource that is returned 
will come from the last dictionary found sequentially in the MergedDictionaries collection. If the 
MergedDictionaries collection was defined in XAML, then the order of the merged dictionaries in the collection is 
the order of the elements as provided in the markup. If a key is defined in the primary dictionary and also in a 
dictionary that was merged, then the resource that is returned will come from the primary dictionary. These 
scoping rules apply equally for both static resource references and dynamic resource references. 

Merged Dictionaries and Code 

Merged dictionaries can be added to a Resources dictionary through code. The default, initially empty 
ResourceDictionary that exists for any Resources property also has a default, initially empty MergedDictionaries 







collection property. To add a merged dictionary through code, you obtain a reference to the desired primary 
ResourceDictionary, get its MergedDictionaries property value, and call Add on the generic Collection that is 
contained in MergedDictionaries. The object you add must be a new ResourceDictionary. In code, you do not set the 
Source property. Instead, you must obtain a ResourceDictionary object by either creating one or loading one. One 
way to load an existing ResourceDictionary to call XamIReader.Load on an existing XAML file stream that has a 
ResourceDictionary root, then casting the XamIReader.Load return value to ResourceDictionary. 

Merged Resource Dictionary URIs 

There are several techniques for how to include a merged resource dictionary, which are indicated by the uniform 
resource identifier (URI) format that you will use. Broadly speaking, these techniques can be divided into two 
categories: resources that are compiled as part of the project, and resources that are not compiled as part of the 
project. 

For resources that are compiled as part of the project, you can use a relative path that refers to the resource 
location. The relative path is evaluated during compilation. Your resource must be defined as part of the project as a 
Resource build action. If you include a resource .xami file in the project as Resource, you do not need to copy the 
resource file to the output directory, the resource is already included within the compiled application. You can also 
use Content build action, but you must then copy the files to the output directory and also deploy the resource files 
in the same path relationship to the executable. 


NOTE 

Do not use the Embedded Resource build action. The build action itself is supported for WPF applications, but the resolution 
of Source does not incorporate ResourceManager, and thus cannot separate the individual resource out of the stream. You 
could still use Embedded Resource for other purposes so long as you also used ResourceManager to access the resources. 


A related technique is to use a Pack URI to a XAML file, and refer to it as Source. Pack URI enables references to 
components of referenced assemblies and other techniques. For more information on Pack URIs, see WPF 
Application Resource, Content, and Data Files. 

For resources that are not compiled as part of the project, the URI is evaluated at run time. You can use a common 
URI transport such as file: or http: to refer to the resource file. The disadvantage of using the noncompiled resource 
approach is that file: access requires additional deployment steps, and http: access implies the Internet security 
zone. 

Reusing Merged Dictionaries 

You can reuse or share merged resource dictionaries between applications, because the resource dictionary to 
merge can be referenced through any valid uniform resource identifier (URI). Exactly how you do this will depend 
on your application deployment strategy and which application model you follow. The aforementioned Pack URI 
strategy provides a way to commonly source a merged resource across multiple projects during development by 
sharing an assembly reference. In this scenario the resources are still distributed by the client, and at least one of 
the applications must deploy the referenced assembly. It is also possible to reference merged resources through a 
distributed URI that uses the http protocol. 

Writing merged dictionaries as local application files or to local shared storage is another possible merged 
dictionary / application deployment scenario. 

Localization 

If resources that need to be localized are isolated to dictionaries that are merged into primary dictionaries, and kept 
as loose XAML, these files can be localized separately. This technique is a lightweight alternative to localizing the 
satellite resource assemblies. For details, see WPF Globalization and Localization Overview. 


See also 
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The topics in this section describe how to use Windows Presentation Foundation (WPF) resources. 

In This Section 

Define and Reference a Resource 
Use Application Resources 
Use SystemFonts 
Use System Fonts Keys 
Use System Parameters 
Use System Parameters Keys 

Reference 

Resources 
SystemColors 
System Parameters 
SystemFonts 

Related Sections 


XAML Resources 
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This example shows how to define a resource and reference it by using an attribute in Extensible Application 
Markup Language (XAML). 

Example 

The following example defines two types of resources: a SolidColorBrush resource, and several Style resources. The 
SolidColorBrush resource Mysrush is used to provide the value of several properties that each take a Brush type 
value. The Style resources Pagesackground , TitieText and Label each target a particular control type. The styles 
set a variety of different properties on the targeted controls, when that style resource is referenced by resource key 
and is used to set the Style property of several specific control elements defined in XAML. 

Note that one of the properties within the setters of the Label style also references the MyBrush resource defined 
earlier. This is a common technique, but it is important to remember that resources are parsed and entered into a 
resource dictionary in the order that they are given. Resources are also requested by the order found within the 
dictionary if you use the StaticResource Markup Extension to reference them from within another resource. Make 
sure that any resource that you reference is defined earlier within the resources collection than where that 
resource is then requested. If necessary, you can work around the strict creation order of resource references by 
using a DynamicResource Markup Extension to reference the resource at runtime instead, but you should be aware 
that this DynamicResource technique has performance consequences. For details, see XAML Resources. 







<Page Name="root" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<Page.Resources> 

cSolidColorBrush x:Key="MyBrush" Color="Gold"/> 

<Style TargetType="Border" x:Key="PageBackground"> 

<Setter Property="Bacl<ground" \/alue="Blue"/> 

</Style> 

<Style TargetType="TextBlock" x:Key="TitleText"> 

<Setter Property="Background" \/alue="Blue"/> 

<Setter Property="DockPanel.Dock" \/alue="Top"/> 

<Setter Property="FontSize" \/alue="18"/> 

<Setter Property="Foreground" \/alue="#4E87D4"/> 

<Setter Property="FontFamily" \/alue="Trebuchet MS"/> 

<Setter Property="Margin" \/alue="0,40jl0jl0"/> 

</Style> 

<Style TargetType="TextBlock" x:Key="Label"> 

<Setter Property="DockPanel.Dock" \/alue="Right"/> 

<Setter Property="FontSize" \/alue="8"/> 

<Setter Property="Foreground" \/alue="{StaticResource MyBrush}"/> 

<Setter Property="FontFamily" \/alue="Arial"/> 

<Setter Property="FontWeight" \/alue="Bold"/> 

<Setter Property="Margin" \/alue="0,3jl0j0"/> 

</Style> 

</Page.Resources> 

<StackPanel> 

<Border Style="{StaticResource PageBackground}"> 

<DockPanel> 

cTextBlock Style="{StaticResource TitleText}">Title</TextBlock> 

<TextBlock Style="{StaticResource Label}">Label</TextBlock> 

<TextBlock DockPanel.Dock="Top" FlorizontalAlignment="Left" FontSize="36" Foreground="{StaticResource 
MyBrush}" Text="Text" Margin="20" /> 

<Button DockPanel.Dock="Top" FlorizontalAlignment="Left" Fleight="30" Background="{StaticResource 
MyBrush}" Margin="40">Button</Button) 

<Ellipse DockPanel.Dock="Top" FlorizontalAlignment="Left" Width="100" Fleight="100" Fill=" 
{StaticResource MyBrush}" Margin="40" /> 

</DockPanel> 

</Border> 

</StackPanel> 

</Page> 


See also 

• XAML Resources 


Styling and Templating 
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This example shows how to use application resources. 

Example 

The following example shows an application definition file. The application definition file defines a resource section 
(a value for the Resources property). Resources defined at the application level can be accessed by all other pages 
that are part of the application. In this case, the resource is a declared style. Because a complete style that includes a 
control template can be lengthy, this example omits the control template that is defined within the ContentTemplate 
property setter of the style. 

<Application.Resources> 

<Style TargetType="Button" x:Key="GelButton" > 

<Setter Property="Margin" Value="l,2jl,2"/> 

<Setter Property="HorizontalAlignment" Value="Left"/> 

<Setter Property="Template"> 

<Setter.Value> 


</Setter.Value> 
</Setter> 

</Style> 

</Application.Resources> 


The following example shows a XAML page that references the application-level resource that the previous 
example defined. The resource is referenced by using a StaticResource Markup Extension that specifies the unique 
resource key for the requested resource. No resource with key of "GelButton" is found in the current page, so the 
resource lookup scope for the requested resource continues beyond the current page and into the defined 
application-level resources. 

<StackPanel 
Name="root" 

xmlns="http: //schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

> 

<Button Height="50" Width="250" Style="{StaticResource GelButton}" Content="Button 1" /> 

<Button Height="50" Width="250" Style="{StaticResource GelButton}" Content="Button 2" /> 

</StackPanel> 


See also 

• XAML Resources 

• Application Management Overview 

• How-to Topics 
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This example shows how to use the static resources of the SystemFonts class in order to style or customize a 
button. 

Example 

System resources expose several system-determined values as both resources and properties in order to help you 
create visuals that are consistent with system settings. SystemFonts is a class that contains both system font values 
as static properties, and properties that reference resource keys that can be used to access those values 
dynamically at run time. For example, CaptionFontFamily is a SystemFonts value, and CaptionFontFamilyKey is a 
corresponding resource key. 

In XAML, you can use the members of SystemFonts as either static properties or dynamic resource references 
(with the static property value as the key). Use a dynamic resource reference if you want the font metric to 
automatically update while the application runs; otherwise, use a static value reference. 


NOTE 

The resource keys have the suffix "Key" appended to the property name. 


The following example shows how to access and use the properties of SystemFonts as static values in order to 
style or customize a button. This markup example assigns SystemFonts values to a button. 

<Button Mar'gin="10j 10 , 5 , 5" Grid.Column="0" Grid.Row="3" 

FontSize="{x:Static SystemFonts.IconFontSize}" 

FontWeight="{x:Static SystemFonts.MessageFontWeight}" 

FontFamily="{x:Static SystemFonts.CaptionFontFamily}"> 

SystemFonts 

</Button> 


To use the values of SystemFonts in code, you do not have to use either a static value or a dynamic resource 
reference. Instead, use the non-key properties of the SystemFonts class. Although the non-key properties are 
apparently defined as static properties, the run-time behavior of WPF as hosted by the system will reevaluate the 
properties in real time and will properly account for user-driven changes to system values. The following example 
shows how to specify the font settings of a button. 

Button btncsharp = new Button(); 
btncsharp.Content = "SystemFonts"; 

btncsharp.Background = SystemColors.ControlDarkDarkBrush; 
btncsharp.FontSize = SystemFonts.IconFontSize; 
btncsharp.FontWeight = SystemFonts.MessageFontWeight; 
btncsharp.FontFamily = SystemFonts.CaptionFontFamily; 
cvl.Children.Add(btncsharp); 







Dim btn As New Button() 
btn.Content = "SystemFonts" 

btn.Background = SystemColors.ControlDarkDarkBrush 
btn.FontSize = SystemFonts.IconFontSize 
btn.FontWeight = SystemFonts.MessageFontWeight 
btn.FontFamily = SystemFonts.CaptionFontFamily 
cvl.Children.Add(btn) 


See also 

• SystemFonts 

• Paint an Area with a System Brush 

• Use SystemParameters 

• Use System Fonts Keys 

• How-to Topics 

• xiStatic Markup Extension 

• XAML Resources 

• DynamicResource Markup Extension 
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System resources expose a number of system metrics as resources to help developers create visuals that are 
consistent with system settings. SystemFonts is a class that contains both system font values and system font 
resources that bind to the values—for example, CaptionFontFamily and CaptionFontFamilyKey. 

System font metrics can be used as either static or dynamic resources. Use a dynamic resource if you want the font 
metric to update automatically while the application runs; otherwise use a static resource. 


NOTE 

Dynamic resources have the keyword /Cey appended to the property name. 


The following example shows how to access and use system font dynamic resources to style or customize a button. 
This XAML example creates a button style that assigns SystemFonts values to a button. 

Example 

<Style x:Key="SimpleFont" TargetType="{x:Type Button}"> 

<Setter Property = "FontSize" Value= "{DynamicResource {x:Static SystemFonts.IconFontSizeKey}}"/> 

<Setter Property = "FontWeight" Value= "{DynamicResource {x:Static SystemFonts.MessageFontWelghtKey}}"/> 
<Setter Property = "FontFamlly" Value= "{DynamicResource {x:Static SystemFonts.CaptionFontFamilyKey}}"/> 
</Style> 


See also 

• Paint an Area with a System Brush 

• Use System Para meters 

• Use SystemFonts 
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This example shows how to access and use the properties of SystemParameters in order to style or customize a 
button. 

Example 

System resources expose several system based settings as resources in order to help you create visuals that are 
consistent with system settings. SystemParameters is a class that contains both system parameter value 
properties, and resource keys that bind to the values. For example, FullPrimaryScreenHeight is a 
SystemParameters property value and FullPrimaryScreenHeightKey is the corresponding resource key. 

In XAML, you can use the members of SystemParameters as either a static property usage, or a dynamic resource 
references (with the static property value as the key). Use a dynamic resource reference if you want the system 
based value to update automatically while the application runs; otherwise, use a static reference. Resource keys 
have the suffix Key appended to the property name. 

The following example shows how to access and use the static values of SystemParameters to style or customize a 
button. This markup example sizes a button by applying SystemParameters values to a button. 

<Button FontSize="8" Margin="10, 10 , 5 , 5" Grid.Column="0" Grid.Row="5" 

HorizontalAlignment="Left" 

Height="{x:Static SystemParameters.CaptionHeight}" 

Width="{x:Static SystemParameters.IconGridWidth}"> 

SystemParameters 

</Button> 


To use the values of SystemParameters in code, you do not have to use either static references or dynamic 
resource references. Instead, use the values of the SystemParameters class. Although the non-key properties are 
apparently defined as static properties, the runtime behavior of WPF as hosted by the system will reevaluate the 
properties in realtime, and will properly account for user-driven changes to system values. The following example 
shows how to set the width and height of a button by using SystemParameters values. 

Button btncshanp = new Button(); 
btncsharp.Content = "SystemParameters"; 
btncsharp.FontSize = 8; 

btncsharp.Background = SystemColors.ControlDarkDarkBrush; 
btncsharp.Fleight = SystemParameters.CaptionHeight; 
btncsharp.Width = SystemParameters.IconGridWidth; 
cv2.Children.Add(btncsharp); 


Dim btn As New Button() 

btn.Content = "SystemParameters" 

btn.FontSize = 8 

btn.Background = SystemColors.ControlDarkDarkBrush 
btn.Height = SystemParameters.CaptionHeight 
btn.Width = SystemParameters.IconGridWidth 
cv2.Children.Add(btn) 


See also 







System Parameters 

Paint an Area with a System Brush 

Use System Fonts 

Use System Parameters Keys 

How-to Topics 
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System resources expose a number of system metrics as resources to help developers create visuals that are 
consistent with system settings. System Para meters is a class that contains both system parameter values and 
resource keys that bind to the values—for example, FullPrimaryScreenHeight and FullPrimaryScreenHeightKey. 
System parameter metrics can be used as either static or dynamic resources. Use a dynamic resource if you want 
the parameter metric to update automatically while the application runs; otherwise use a static resource. 


NOTE 

Dynamic resources have the keyword /Cey appended to the property name. 


The following example shows how to access and use system parameter dynamic resources to style or customize a 
button. This XAML example sizes a button by assigning System Parameters values to the button's width and height. 

Example 

<Style x:Key="SimpleParam" Tar'getType="{x:Type Button}"> 

<Setter Property = "Height" Value= "{DynamicResource {x:Static SystemParameters.CaptionHeightKey}}"/> 
<Setter Property = "Width" Value= "{DynamicResource {xrStatic SystemParameters.IconGridWidthKey}}"/> 
</Style> 


See also 

• Paint an Area with a System Brush 

• Use SystemFonts 

• Use System Para meters 
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Windows Presentation Foundation (WPF) provides a versatile set of components that enable developers to build 
applications with advanced document features and an improved reading experience. In addition to enhanced 
capabilities and quality, Windows Presentation Foundation (WPF) also provides simplified management services 
for document packaging, security, and storage. 

In This Section 

Documents in WPF 

Document Serialization and Storage 

Annotations 

Flow Content 

Typography 

Printing and Print System Management 

See also 

• DocumentViewer 

• FlowDocument 

• System.Windows.Xps 

• isXPS.exe (isXPS Conformance Tool) 
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Windows Presentation Foundation (WPF) offers a wide range of document features that enable the creation of 
high-fidelity content that is designed to be more easily accessed and read than in previous generations of 
Windows. In addition to enhanced capabilities and quality, WPF also provides integrated services for document 
display, packaging, and security. This topic provides an introduction to WPF document types and document 
packaging. 

Types of Documents 

WPF divides documents into two broad categories based on their intended use; these document categories are 
termed "fixed documents" and "flow documents." 

Fixed documents are intended for applications that require a precise "what you see is what you get" 

(WYSIWYG) presentation, independent of the display or printer hardware used. Typical uses for fixed 
documents include desktop publishing, word processing, and form layout, where adherence to the original 
page design is critical. As part of its layout, a fixed document maintains the precise positional placement of 
content elements independent of the display or print device in use. For example, a fixed document page viewed 
on 96 dpi display will appear exactly the same when it is output to a 600 dpi laser printer as when it is output 
to a 4800 dpi phototypesetter. The page layout remains the same in all cases, while the document quality 
maximizes to the capabilities of each device. 

By comparison, flow documents are designed to optimize viewing and readability and are best utilized when 
ease of reading is the primary document consumption scenario. Rather than being set to one predefined 
layout, flow documents dynamically adjust and reflow their content based on run-time variables such as 
window size, device resolution, and optional user preferences. A Web page is a simple example of a flow 
document where the page content is dynamically formatted to fit the current window. Flow documents 
optimize the viewing and reading experience for the user, based on the runtime environment. For example, the 
same flow document will dynamically reformat for optimal readability on either high-resolution 19-inch 
display or a small 2x3-inch PDA screen. In addition, flow documents have a number of built in features 
including search, viewing modes that optimize readability, and the ability to change the size and appearance of 
fonts. See Flow Document Overview for illustrations, examples, and in-depth information on flow documents. 

Document Controls and Text Layout 

The .NET Framework provides a set of pre-built controls that simplify using fixed documents, flow documents, 
and general text within your application. The display of fixed document content is supported using the 
DocumentViewer control. Display of flow document content is supported by three different controls: 
FlowDocumentReader, FlowDocumentPageViewer, and FlowDocumentScrollViewer which map to different 
user scenarios (see sections below). Other WPF controls provide simplified layout to support general text uses 
(see Text in the User Interface, below). 

Fixed Document Control - DocumentViewer 

The DocumentViewer control is designed to display FixedDocument content. The DocumentViewer control 
provides an intuitive user interface that provides built-in support for common operations including print 
output, copy to clipboard, zoom, and text search features. The control provides access to pages of content 
through a familiar scrolling mechanism. Like all WPF controls, DocumentViewer supports complete or partial 
restyling, which enables the control to be visually integrated into virtually any application or environment. 




DocumentViewer is designed to display content in a read-only manner; editing or modification of content is 
not available and is not supported. 

Flow Document Controls 

NOTE 

For more detailed information on flow document features and how to create them, see Flow Document Overview. 


Display of flow document content is supported by three controls: FlowDocumentReader, 
FlowDocumentPageViewer, and FlowDocumentScrollViewer. 

FlowDocumentReader 

FlowDocumentReader includes features that enable the user to dynamically choose between various viewing 
modes, including a single-page (page-at-a-time) viewing mode, a two-page-at-a-time (book reading format) 
viewing mode, and a continuous scrolling (bottomless) viewing mode. For more information about these 
viewing modes, see FlowDocumentReaderViewingMode. If you do not need the ability to dynamically switch 
between different viewing modes, FlowDocumentPageViewer and FlowDocumentScrollViewer provide lighter- 
weight flow content viewers that are fixed in a particular viewing mode. 

FlowDocumentPageViewer and FlowDocumentScrollViewer 

FlowDocumentPageViewer shows content in page-at-a-time viewing mode, while FlowDocumentScrollViewer 
shows content in continuous scrolling mode. Both FlowDocumentPageViewer and FlowDocumentScrollViewer 
are fixed to a particular viewing mode. Compare to FlowDocumentReader, which includes features that enable 
the user to dynamically choose between various viewing modes (as provided by the 
FlowDocumentReaderViewingMode enumeration), at the cost of being more resource intensive than 
FlowDocumentPageViewer or FlowDocumentScrollViewer. 

By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The 
default Ul for FlowDocumentScrollViewer does not include a toolbar; however, the IsToolBarVisible property 
can be used to enable a built-in toolbar. 

Text in the User Interface 

Besides adding text to documents, text can obviously be used in application Ul such as forms. WPF includes 
multiple controls for drawing text to the screen. Each control is targeted to a different scenario and has its own 
list of features and limitations. In general, the TextBlock element should be used when limited text support is 
required, such as a brief sentence in a user interface (Ul). Label can be used when minimal text support is 
required. For more information, see TextBlock Overview. 

Document Packaging 

The System.lO.Packaging APIs provide an efficient means to organize application data, document content, and 
related resources in a single container that is simple to access, portable, and easy to distribute. A ZIP file is an 
example of a Package type capable of holding multiple objects as a single unit. The packaging APIs provide a 
default ZipPackage implementation designed using an Open Packaging Conventions standard with XML and 
ZIP file architecture. The WPF packaging APIs make it simple to create packages, and to store and access 
objects within them. An object stored in a Package is referred to as a PackagePart ("part"). Packages can also 
include signed digital certificates that can be used to identify the originator of a part and to validate that the 
contents of a package have not been modified. Packages also include a PackageRelationship feature that allows 
additional information to be added to a package or associated with specific parts without actually modifying 
the content of existing parts. Package services also support Microsoft Windows Rights Management (RM). 

The WPF Package architecture serves as the foundation for a number of key technologies: 

• XPS documents conforming to the XML Paper Specification (XPS). 



• Microsoft Office "12" open XML format documents (.docx). 

• Custom storage formats for your own application design. 

Based on the packaging APIs, an XpsDocument is specifically designed for storing WPF fixed content 
documents. An XpsDocument is a self-contained document that can be opened in a viewer, displayed in a 
DocumentViewer control, routed to a print spool, or output directly to an XPS-compatible printer. 

The following sections provide additional information on the Package and XpsDocument APIs provided with 
WPF. 

Package Components 

The WPF packaging APIs allow application data and documents to be organized into a single portable unit. A 
ZIP file is one of the most common types of packages and is the default package type provided with WPF. 
Package itself is an abstract class from which ZipPackage is implemented using an open standard XML and ZIP 
file architecture. The Open method uses ZipPackage to create and use ZIP files by default. A package can 
contain three basic types of items: 


PackagePart Application content, data, documents, and resource files. 

PackageDigitalSignature [X.509 Certificate] for identification, authentication and 

validation. 

PackageRelationship Added information related to the package or a specific part. 


PackageParts 

A PackagePart ("part") is an abstract class that refers to an object stored in a Package. In a ZIP file, the package 
parts correspond to the individual files stored within the ZIP file. ZipPackagePart provides the default 
implementation for serializable objects stored in a ZipPackage. Like a file system, parts contained in the 
package are stored in hierarchical directory or "folder-style" organization. Using the WPF packaging APIs, 
applications can write, store, and read multiple PackagePart objects using a single ZIP file container. 

PackageDigitalSignatures 

For security, a PackageDigitalSignature ("digital signature") can be associated with parts within a package. A 
PackageDigitalSignature incorporates a [509] that provides two features: 

1. Identifies and authenticates the originator of the part. 

2. Validates that the part has not been modified. 

The digital signature does not preclude a part from being modified, but a validation check against the digital 
signature will fail if the part is altered in any way. The application can then take appropriate action—for 
example, block opening the part or notify the user that the part has been modified and is not secure. 

PackageRelationships 

A PackageRelationship ("relationship") provides a mechanism for associating additional information with the 
package or a part within the package. A relationship is a package-level facility that can associate additional 
information with a part without modifying the actual part content. Inserting new data directly into the part 
content of is usually not practical in many cases: 

• The actual type of the part and its content schema is not known. 

• Even if known, the content schema might not provide a means for adding new information. 

• The part might be digitally signed or encrypted, precluding any modification. 

Package relationships provide a discoverable means for adding and associating additional information with 


individual parts or with the entire package. Package relationships are used for two primary functions: 

1. Defining dependency relationships from one part to another part. 

2. Defining information relationships that add notes or other data related to the part. 

A PackageRelationship provides a quick, discoverable means to define dependencies and add other 
information associated with a part of the package or the package as a whole. 

Dependency Relationships 

Dependency relationships are used to describe dependencies that one part makes to other parts. For example, 
a package might contain an HTML part that includes one or more <img> image tags. The image tags refer to 
images that are located either as other parts internal to the package or external to the package (such as 
accessible over the Internet). Creating a PackageRelationship associated with HTML file makes discovering and 
accessing the dependent resources quick and easy. A browser or viewer application can directly access the part 
relationships and immediately begin assembling the dependent resources without knowing the schema or 
parsing the document. 

Information Relationships 

Similar to a note or annotation, a PackageRelationship can also be used to store other types of information to 
be associated with a part without having to actually modify the part content itself 

XPS Documents 

XML Paper Specification (XPS) document is a package that contains one or more fixed-documents along with 
all the resources and information required for rendering. XPS is also the native Windows Vista print spool file 
format. An XpsDocument is stored in standard ZIP dataset, and can include a combination of XML and binary 
components, such as image and font files. PackageRelationships are used to define the dependencies between 
the content and the resources required to fully render the document. The XpsDocument design provides a 
single, high-fidelity document solution that supports multiple uses: 

• Reading, writing, and storing fixed-document content and resources as a single, portable, and easy-to- 
distribute file. 

• Displaying documents with the XPS Viewer application. 

• Outputting documents in the native print spool output format of Windows Vista. 

• Routing documents directly to an XPS-compatible printer. 

See also 

• FixedDocument 

• FlowDocument 

• XpsDocument 

• ZipPackage 

• ZipPackagePart 

• PackageRelationship 

• DocumentViewer 

• Text 

• Flow Document Overview 

• Printing Overview 

• Document Serialization and Storage 
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Microsoft .NET Framework provides a powerful environment for creating and displaying high quality documents. 
Enhanced features that support both fixed-documents and flow-documents, advanced viewing controls, combined 
with powerful 2D and 3D graphic capabilities take .NET Framework applications to a new level of quality and user 
experience. Being able to flexibly manage an in-memory representation of a document is a key feature of .NET 
Framework, and being able to efficiently save and load documents from a data store is a need of almost every 
application. The process of converting a document from an internal in-memory representation to an external data 
store is termed serialization. The reverse process of reading a data store and recreating the original in-memory 
instance is termed deserialization. 

About Document Serialization 

Ideally the process of serializing and deserializing a document from and then back into memory is transparent to 
the application. The application calls a serializer "write" method to save the document, while a deserializer "read" 
method accesses the data store and recreates the original instance in memory. The specific format that the data is 
stored in is generally not a concern of the application as long as the serialize and deserialize process recreates the 
document back to its original form. 

Applications often provide multiple serialization options which allow the user to save documents to different 
medium or to a different format. For example, an application might offer "Save As" options to store a document to 
a disk file, database, or web service. Similarly, different serializers could store the document in different formats 
such as in HTML, RTF, XML, XPS, or alternately to a third-party format. To the application, serialization defines an 
interface that isolates the details of the storage medium within the implementation of each specific serializer. In 
addition to the benefits of encapsulating storage details, the .NET Framework 
System.Windows.Documents.Serialization APIs provide several other important features. 

Features of .NET Framework 3.0 Document Serializers 

• Direct access to the high-level document objects (logical tree and visuals) enable efficient storage of 
paginated content, 2D/3D elements, images, media, hyperlinks, annotations, and other support content. 

• Synchronous and asynchronous operation. 

• Support for plug-in serializers with enhanced capabilities: 

o System-wide access for use by all .NET Framework applications, 
o Simple application plug-in discoverability. 

o Simple deployment, installation, and update for custom third-party plug-ins. 
o User interface support for custom run-time settings and options. 

XPS Print Path 

The Microsoft .NET Framework XPS print path also provides an extensible mechanism for writing documents 
through print output. XPS serves as both a document file format and is the native print spool format for Windows 
Vista. XPS documents can be sent directly to XPS-compatible printers without the need for conversion to an 
intermediate format. See the Printing Overview for additional information on print path output options and 
capabilities. 


Plug-in Serializers 




The System.Windows.Documents.Serialization APIs provide support for both plug-in serializers and linked 
serializers that are installed separately from the application, bind at run time, and are accessed by using the 
SerializerProvider discovery mechanism. Plug-in serializers offer enhanced benefits for ease of deployment and 
system-wide use. Linked serializers can also be implemented for partial trust environments such as XAML browser 
applications (XBAPs) where plug-in serializers are not accessible. Linked serializers, which are based on a derived 
implementation of the SerializerWriter class, are compiled and linked directly into the application. Both plug-in 
serializers and linked serializers operate through identical public methods and events which make it easy to use 
either or both types of serializers in the same application. 

Plug-in serializers aid application developers by providing extensibility to new storage designs and file formats 
without having to code directly for every potential format at build time. Plug-in serializers also benefit third-party 
developers by providing a standardized means to deploy, install, and update system accessible plug-ins for custom 
or proprietary file formats. 

Using a Plug-in Serializer 

Plug-in serializers are simple to use. The SerializerProvider class enumerates a SerializerDescriptor object for each 
plug-in installed on the system. The IsLoadable property filters the installed plug-ins based on the current 
configuration and verifies that the serializer can be loaded and used by the application. The SerializerDescriptor 
also provides other properties, such as DisplayName and DefaultFileExtension, which the application can use to 
prompt the user in selecting a serializer for an available output format. A default plug-in serializer for XPS is 
provided with .NET Framework and is always enumerated. After the user selects an output format, the 
CreateSerializerWriter method is used to create a SerializerWriter for the specific format. The SerializerWriter.Write 
method can then be called to output the document stream to the data store. 

The following example illustrates an application that uses the SerializerProvider method in a "PlugInFileFilter" 
property. PlugInFileFilter enumerates the installed plug-ins and builds a filter string with the available file options 
for a SaveFileDialog. 


II - PluglnFileFilten - 

III <summar'y> 

III Gets a filter string for installed plug-in serializers.</summary> 
III <remark> 

III PlugInFileFilter is used to set the SaveFileDialog or 

III OpenFileDialog "Filter" property when saving or opening files 

III using plug-in serializers.</remark> 

private string PlugInFileFilter 

{ 

get 

{ // Create a SerializerProvider for accessing plug-in serializers. 

SerializerProvider SerializerProvider = new SerializerProvider(); 
string filter = 

// For each loadable serializer^ add its display 
// name and extension to the filter string, 
foreach (SerializerDescriptor serializerDescriptor in 
SerializerProvider.InstalledSerializers) 

{ 

if (serializerDescriptor.IsLoadable) 

{ 

// After the firsts separate entries with a "|". 
if (filter.Length > 0) filter += 

// Add an entry with the plug-in name and extension, 
filter += serializerDescriptor.DisplayName + " (*" + 
serializerDescriptor.DefaultFileExtension + ")|*" + 
serializerDescriptor.DefaultFileExtension; 

} 

} 

// Return the filter string of installed plug-in serializers, 
return filter; 

} 

} 


After an output file name has been selected by the user, the following example illustrates use of the 
CreateSerializerWriter method to store a given document in a specified format. 





// Create a SerializerProvider for accessing plug-in serializers. 
SerializerProvider SerializerProvider = new SerializerProvider(); 


// Locate the serializer that matches the fileName extension. 

SerializerDescriptor selectedPlugIn = null; 

foreach ( SerializerDescriptor SerializerDescriptor in 

SerializerProvider.InstalledSerializers ) 


if ( SerializerDescriptor.IsLoadable && 

fileName.EndsWith(SerializerDescriptor.DefaultFileExtension) ) 
{ // The plug-in serializer and fileName extensions match. 

selectedPlugIn = SerializerDescriptor; 
break; // foreach 


} 


} 


// If a match for a plug-in serializer was found, 

// use it to output and store the document, 
if (selectedPlugIn != null) 

{ 

Stream package = File.Create(fileName); 

SerializerWriter serializerWriter = 

SerializerProvider.GreateSerializerWriter(selectedPlugIn, 

package); 

IDocumentPaginatorSource idoc = 

flowDocument as IDocumentPaginatorSource; 
serializerWriter.Write(idoc.DocumentPaginator, null); 
package.CloseO; 
return true; 

} 


Installing Plug-in Serializers 

The SerializerProvider class supplies the upper-level application interface for plug-in serializer discovery and 
access. SerializerProvider locates and provides the application a list of the serializers that are installed and 
accessible on the system. The specifics of the installed serializers are defined through registry settings. Plug-in 
serializers can be added to the registry by using the RegisterSerializer method; or if .NET Framework is not yet 
installed, the plug-in installation script can directly set the registry values itself The UnregisterSerializer method 
can be used to remove a previously installed plug-in, or the registry settings can be reset similarly by an uninstall 
script. 

Creating a Plug-in Serializer 

Both plug-in serializers and linked serializers use the same exposed public methods and events, and similarly can 
be designed to operate either synchronously or asynchronously. There are three basic steps normally followed to 
create a plug-in serializer: 

1. Implement and debug the serializer first as a linked serializer. Initially creating the serializer compiled and 
linked directly in a test application provides full access to breakpoints and other debug services helpful for 
testing. 

2. After the serializer is fully tested, an ISerializerFactory interface is added to create a plug-in. The 
ISerializerFactory interface permits full access to all .NET Framework objects which includes the logical tree, 
UlElement objects, IDocumentPaginatorSource, and Visual elements. Additionally ISerializerFactory provides 
the same synchronous and asynchronous methods and events used by linked serializers. Since large 
documents can take time to output, asynchronous operations are recommended to maintain responsive 
user interaction and offer a "Cancel" option if some problem occurs with the data store. 

3. After the plug-in serializer is created, an installation script is implemented for distributing and installing 
(and uninstalling) the plug-in (see above, "Installing Plug-in Serializers"). 



See also 

• System.Windows.Documents.Serialization 

• XpsDocumentWriter 

• XpsDocument 

• Documents in WPF 

• Printing Overview 

• XML Paper Specification 
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Windows Presentation Foundation (WPF) provides document viewing controls that support annotating document 
content. 

In This Section 

Annotations Overview 
Annotations Schema 

Reference 

Annotation 

AnnotationService 

DocumentViewer 

Related Sections 

Documents in WPF 
Flow Document Overview 
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Writing notes or comments on paper documents is such a commonplace activity that we almost take it for granted. 
These notes or comments are "annotations" that we add to a document to flag information or to highlight items of 
interest for later reference. Although writing notes on printed documents is easy and commonplace, the ability to 
add personal comments to electronic documents is typically very limited, if available at all. 

This topic reviews several common types of annotations, specifically sticky notes and highlights, and illustrates 
how the Microsoft Annotations Framework facilitates these types of annotations in applications through the 
Windows Presentation Foundation (WPF) document viewing controls. WPF document viewing controls that 
support annotations include FlowDocumentReader and FlowDocumentScrollViewer, as well as controls derived 
from DocumentViewerBase such as DocumentViewer and FlowDocumentPageViewer. 


Sticky Notes 

A typical sticky note contains information written on a small piece of colored paper that is then "stuck" to a 
document. Digital sticky notes provide similar functionality for electronic documents, but with the added flexibility 
to include many other types of content such as typed text, handwritten notes (for example. Tablet PC "ink" strokes), 
or Web links. 


The following illustration shows some examples of highlight, text sticky note, and ink sticky note annotations. 
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Here is a text note annotation created on the 
selection "features available" above. 

A yellow highlight annotabon has been 
added to the text "become more efficient”, 
lower-left. 

An ink-note has also been created on the 
selection "easier to train new staff” below. 
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The following example shows the method that you can use to enable annotation support in your application. 












// - StartAnnotations - 

III <summary> 

III Enables annotations and displays all that are viewable.</summary> 
private void StartAnnotations() 

{ 

// If there is no AnnotationService yet, create one. 
if (_annotService == null) 

// docViewer is a document viewing control named in Windowl.xaml. 
_annotService = new AnnotationService(docViewer)j 

// If the AnnotationService is currently enabled, disable it. 
if (_annotService.IsEnabled == true) 

_annotService.Disable(); 

// Open a stream to the file for storing annotations. 

_annotStream = new FileStream( 

_annotStorePath, FileMode.OpenOrCreate, FileAccess.ReadWrite); 

// Create an AnnotationStore using the file stream. 

_annotStore = new XmlStreamStore(_annotStream)j 

// Enable the AnnotationService using the new store. 

_annotService.Enable(_annotStore); 

}// end:StartAnnotations() 


■ - StartAnnotations - 

' ' ' <summary> 

' '' Enables annotations and displays all that are viewable.</summary> 

Private Sub StartAnnotations() 

' If there is no AnnotationService yet, create one. 

If _annotService Is Nothing Then 

' docViewer is a document viewing control named in Windowl.xaml. 

_annotService = New AnnotationService(docViewer) 

End If 

' If the AnnotationService is currently enabled, disable it. 

If _annotService.IsEnabled = True Then 
_annotService.Disable() 

End If 

' Open a stream to the file for storing annotations. 

_annotStream = New FileStream(_annotStorePath, FileMode.OpenOrCreate, FileAccess.ReadWrite) 

' Create an AnnotationStore using the file stream. 

_annotStore = New XmlStreamStore(_annotStream) 

' Enable the AnnotationService using the new store. 

_annotService.Enable(_annotStore) 

End Sub 


Highlights 

People use creative methods to draw attention to items of interest when they mark up a paper document, such as 
underlining, highlighting, circling words in a sentence, or drawing marks or notations in the margin. Highlight 
annotations in Microsoft Annotations Framework provide a similar feature for marking up information displayed 
in WPF document viewing controls. 

The following illustration shows an example of a highlight annotation. 

Highlight The Microsoft Annotation Framework makes 
it easy to add annotation capabilities to 
virtually any application. 







Users typically create annotations by first selecting some text or an item of interest, and then right-clicking to 
display a ContextMenu of annotation options. The following example shows the Extensible Application Markup 
Language (XAML) you can use to declare a ContextMenu with routed commands that users can access to create 
and manage annotations. 

<DocumentViewer.ContextMenu> 

<ContextMenu> 

<MenuItem Command="ApplicationCommands.Copy" /> 

<Separ'ator' /> 

<!-- Add a Highlight annotation to a user selection. --> 

<MenuItem Command="ann:AnnotationService.CreateHighlightCommand" 

Header="Add Highlight" /> 

<!-- Add a Text Note annotation to a user selection. --> 

<MenuItem Command="ann:AnnotationService.CreateTextStickyNoteCommand" 

Header="Add Text Note" /> 

<!-- Add an Ink Note annotation to a user selection. --> 

<MenuItem Command="ann:AnnotationService.CreateInkStickyNoteCommand" 

Header="Add Ink Note" /> 

<Separator /> 

<!-- Remove Highlights from a user selection. --> 

<MenuItem Command="ann:AnnotationService.ClearHighlightsCommand" 

Header="Remove Highlights" /> 

<!-- Remove Text Notes and Ink Notes from a user selection. --> 

<MenuItem Command="ann:AnnotationService.DeleteStickyNotesCommand" 

Header="Remove Notes" /> 

<!-- Remove Highlights^ Text Notes^ Ink Notes from a selection. --> 

<MenuItem Command="ann:AnnotationService.DeleteAnnotationsCommand" 

Header="Remove Highlights Samp; Notes" /> 

</ContextMenu> 

c/DocumentViewer.ContextMenu) 


Data Anchoring 

The Annotations Framework binds annotations to the data that the user selects, not just to a position on the display 
view. Therefore, if the document view changes, such as when the user scrolls or resizes the display window, the 
annotation stays with the data selection to which it is bound. For example, the following graphic illustrates an 
annotation that the user has made on a text selection. When the document view changes (scrolls, resizes, scales, or 
otherwise moves), the highlight annotation moves with the original data selection. 
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Matching Annotations with Annotated Objects 

You can match annotations with the corresponding annotated objects. For example, consider a simple document 
reader application that has a comments pane. The comments pane might be a list box that displays the text from a 
list of annotations that are anchored to a document. If the user selects an item in the list box, then the application 
brings into view the paragraph in the document that the corresponding annotation object is anchored to. 

The following example demonstrates how to implement the event handler of such a list box that serves as the 
comments pane. 



void annotationsListBox_SelectionChanged(object sendsTj SelectionChangedEventArgs e) 

{ 

Annotation comment = (sender as ListBox).Selecteditem as Annotation; 
if (comment != null) 

{ 

// lAnchorInfo info; 

// service is an AnnotationService object 
// comment is an Annotation object 

info = AnnotationHelper.GetAnchorInfo(this.servicej comment); 

TextAnchor resolvedAnchor = info.ResolvedAnchor as TextAnchor; 

TextPointer textPointer = (TextPointer)resolvedAnchor.BoundingStart; 
textPointer.Paragraph.BringIntoView(); 

} 


Private Sub annotationsListBox_SelectionChanged(ByVal sender As Object^ ByVal e As SelectionChangedEventArgs) 

Dim comment As Annotation = TryCast((TryCast(sender, ListBox)).Selecteditem, Annotation) 

If comment IsNot Nothing Then 

' service is an AnnotationService object 
' comment is an Annotation object 

info = AnnotationHelper.GetAnchorInfo(Me.service, comment) 

Dim resolvedAnchor As TextAnchor = TryCast(info.ResolvedAnchor, TextAnchor) 

Dim textPointer As TextPointer = CType(resolvedAnchor.BoundingStart, TextPointer) 
textPointer.Paragraph.BringIntoView() 

End If 
End Sub 


Another example scenario involves applications that enable the exchange of annotations and sticky notes between 
document readers through email. This feature enables these applications to navigate the reader to the page that 
contains the annotation that is being exchanged. 
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This topic describes the XML schema definition (XSD) used by the Microsoft Annotations Framework to save and 
retrieve user annotation data. 

The Annotations Framework serializes annotation data from an internal representation to an XML format. The XML 
format used for this conversion is described by the Annotations Framework XSD Schema. The schema defines the 
implementation-independent XML format that can be used to exchange annotation data between applications. 

The Annotations Framework XML schema definition consists of two subschemas 

• The Annotations XML Core Schema (Core Schema). 

• The Annotations XML Base Schema (Base Schema). 

The Core Schema defines the primary XML structure of an Annotation. The majority of XML elements defined in 
the Core Schema correspond to types in the System.Windows.Annotations namespace. The Core Schema exposes 
three extension points where applications can add their own XML data. These extension points include the Authors, 
ContentLocatorPart, and "Content". (Content elements are provided in the form of an XmlElement list.) 

The Base Schema described in this topic defines the extensions for the Authors, ContentLocatorPart, and Content 
types included with the initial Windows Presentation Foundation (WPF) release. 


Annotations XML Core Schema 

The Annotations XML Core Schema defines the XML structure that is used to store Annotation objects. 


<xsd: schema elementFor'mDefault="qualified" attributeFormDefault="unqualified" 
blockDefault="#all" 

xmlns:xsd="http://www.w3.org/2001/XMLSchema" 

targetNamespace="http://schemas.microsoft.com/windows/annotations/2003/ll/core" 
xmlns :anc="http://schemas. mlcr'osoft.com/windows/annotations/2003/ll/core"> 

<!-- The Annotations element groups a number of annotations. --> 

<xsd:element name="Annotations" type="anc:AnnotationsType" /> 

<xsd:complexType name="AnnotationsType"> 

<xsd:sequence> 

<xsd:element name="Annotation" minOccurs="0" maxOccurs="unbounded" 
type="anc:AnnotationType" /> 

</xsd:sequence> 

</xsd:complexType> 

<!-- AnnotationType defines the structure of the Annotation element. --> 

<xsd:complexType name="AnnotationType"> 

<xsd:sequence> 


<!-- List of 0 or more authors. --> 

<xsd:element name="Authors" minOccurs="0" maxOccurs="l" 
type="anc:AuthorListType" /> 

<!-- List of 0 or more anchors. --> 

<xsd:element name="Anchors" minOccurs="0" maxOccurs="l" 
type="anc:ResourceListType" /> 


<!-- List of 0 or more cargos. --> 

<xsd:element name="Cargos" minOccurs="0" maxOccurs="l" 




,1 -i f-t-Tvif-.i-. 




Lypc— aiiv..r\c;:^uuiv.c;i-j.:^Liy|Jc /x 


</xsd:sequence> 

<!-- Unique annotation ID. --> 

<xsd:attribute name="Id" type="xsd:string" use="required" /> 

<!-- Annotation "Type" is used to map the annotation to an annotation 
component that takes care of the visual representation of the 
annotation. WPF VI recognizes three annotation types: 
http://schemas.microsoft.com/windows/annotations/2003/ll/base:Highlight 
http://schemas.microsoft.com/windows/annotations/2003/ll/base:TextStickyNote 
http://schemas.microsoft.com/windows/annotations/2003/ll/base:InkStickyNote 
--> 

<xsd:attribute name="Type" type="xsd:QName" use="required" /> 

<!-- Time when the annotation was last modified. --> 

<xsd:attribute name="LastModificationTime" use="optional" 
type="xsd:dateTime" /> 

<!-- Time when the annotation was created. --> 

<xsd:attribute name="CreationTime" use="optional" 
type="xsd:dateTime" /> 

</xsd:complexType> 

<!-- "Authors" consists of 0 or more elements that represent an author. --> 

<xsd:complexType name="AuthorListType"> 

<xsd:sequence minOccurs="0" maxOccurs="unbounded"> 

<xsd:element ref="anc:Author" /> 

</xsd:sequence> 

</xsd:complexType> 

<!-- The core schema allows any author type. Supported author types 
in version 1 (VI) are described in the base schema. --> 

<xsd:element name="Author" abstract="true" block="extension restriction"/> 

<!-- Both annotation anchor and annotation cargo are represented by the 
ResourceListType which contains 0 or more "Resource" elements. --> 

<xsd:complexType name="ResourceListType"> 

<xsd:sequence> 

<xsd:element name="Resource" minOccurs="0" maxOccurs="unbounded" 
type="anc:ResourceType" /> 

</xsd:sequence> 

</xsd:complexType> 

<!-- Resource groups identificationj location 
and/or content of some information. --> 

<xsd:complexType name="ResourceType"> 

<xsd:choice minOccurs="0" maxOccurs="unbounded" > 

<xsd:choice> 

<xsd:element name="ContentLocator" type="anc:ContentLocatorType" /> 

<xsd:element name="ContentLocatorGroup" type="anc:ContentLocatorGroupType" /> 
</xsd:choice> 

<xsd:element ref="anc:Content"/> 

</xsd:choice) 

<!-- Unique resource identifier. --> 

<xsd:attribute name="Id" type="xsd:string" use="required" /> 

<!-- Optional resource name. --> 

<xsd:attribute name="Mame" type="xsd:string" use="optional" /> 

</xsd:complexType) 

<!-- ContentLocatorGroup contains a set of ContentLocators --) 

<xsd:complexType name="ContentLocatorGroupType") 

<xsd:sequence) 

<xsd:element name="ContentLocator" minOccurs="l" maxOccurs="unbounded" 
type="anc:ContentLocatorType" /) 


</xsd:sequence) 


</xsa:complex Iype> 


<!-- A ContentLocator describes the location or the identification 

of particular data within some context. The ContentLocator consists 
of one or more ContentLocatorParts. Each ContentLocatorPart needs to 
be successively applied to the context to arrive at the data. What 
"applying"j "context''^ and "data" mean is application dependent. 

--> 

<xsd:complexlype name="ContentLocatorType"> 

<xsd:sequence minOccurs="l" maxOccurs="unbounded"> 

<xsd:element ref="anc:ContentLocatorPart" /> 

</xsd:sequence> 

</xsd:complexType> 

<!-- A ContentLocatorPart is a set of "Item" elements. Each "Item" element 
has "Name" and "Value" attributes that define a name/value pair. 
ContentLocatorPart is an abstract type that must be restricted for each 
concrete ContentLocatorPart definition. This restriction should define 
allowed names and values for the concrete ContentLocatorPart type. That 
way the application can define its own way of locating information. The 
ContentLocatorPartTypes that are allowed in version 1 (VI) of WPF are 
defined in the Annotations Base Schema. 

--> 

<xsd:element name="ContentLocatorPart" type="anc:ContentLocatorPartType" 
abstract="true" /> 

<xsd:complexType name="ContentLocatorPartType" abstract="true" 
block="restriction"> 

<xsd:sequence minOccurs="0" maxOccurs="unbounded"> 

<xsd:element name="Item" type="anc:ItemType" /> 

</xsd:sequence> 

</xsd:complexType> 

<xsd:complexType name="ItemType" abstract="true" > 

<xsd:attribute name="Name" type='xsd:string' use="required" /> 

<xsd:attribute name="Value" type='xsd:string' use="optional" /> 

</xsd:complexType> 

<!-- Content describes the underlying content of a resource. This is an 
abstract type that should be redefined for each concrete content type 
through restriction. Allowed content types in WPF version 1 are 
defined in the Annotations Base Schema. 

--> 

<xsd:element name="Content" abstract="true" block="extension restriction"/> 
</xsd:schema) 


Annotations XML Base Schema 

The Base Schema defines the XML structure for the three abstract elements defined in the Core Schema - Authors, 
ContentLocatorPart, and Contents. 


<xsd:schema elementFormDefault="qualified" attributeFormDefault="unqualified" 
blockDefault="#all" 

xmlns:xsd="http: //WWW. w3.org/2001/XMLSchema" 

targetNamespace="http://schemas.microsoft.com/windows/annotations/2003/ll/base" 
xmlns:anb="http://schemas.microsoft.com/windows/annotations/2003/ll/base" 
xmlns:anc="http://schemas.microsoft.com/windows/annotations/2003/ll/core"> 

<xsd:import schemaLocation="AnnotationCoreVl.xsd" 

namespace="http://schemas.microsoft.com/windows/annotations/2003/ll/core"/> 

<!-- ***** Author ***** --> 

<!-- Simple DisplayName Author --> 

<xsd:complexType name="StringAuthorType"> 

<xsd:simpleContent > 


<xsd:extension base='xsd:string' /> 

</xsd:simpleContent> 

</xsd:complexType> 

<xsd:element name="StringAuthor" type="anb:StringAuthorType" 
substitutionGroup="anc:Author"/> 

<!-- ***** LocatorParts ***** --> 

<!-- Helper types --> 

<!-- CountItemNameType - helper type to define count item --> 

<xsd: simpleType name="CountItemlMameType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value="Count" /> 

</xsd:restriction> 

</xsd:simpleType> 

<!-- NumberType - helper type to define segment count item --> 

<xsd:simpleType name="NumberType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value="\d*" /> 

</xsd:restriction> 

</xsd:simpleType> 

<!-- SegmentNameType: helper type to define possible segment name types --> 
<xsd:simpleType name="SegmentItemNameType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value="Segment\d*" /> 

</xsd:restriction> 

</xsd:simpleType> 

<!-- Flow Locator Part --> 

<!-- FlowSegmentValueltemType: helper type to define flow segment values --> 
<xsd:simpleType name="FlowSegmentItemValueType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value=" \d*j\d*" /> 

</xsd:restriction> 

</xsd:simpleType> 

<!-- FlowItemType --> 

<xsd:complexType name="FlowItemType" abstract = "true"> 

<xsd:complexContent> 

<xsd:restriction base="anc:ItemType"> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- FlowSegmentItemType --> 

<xsd:complexType name="FlowSegmentItemType"> 

<xsd:complexContent> 

<xsd:restriction base="anb:FlowItemType"> 

<xsd:attribute name="IMame" use="required" 

type="anb:SegmentItemNameType"/> 

<xsd:attribute name="Value" use="required" 

type="anb:FlowSegmentItemValueType"/> 

</xsd:restriction) 

</xsd:complexContent) 

</xsd:complexType) 

<!-- FlowCountItemType --) 

<xsd:complexType name="FlowCountItemType") 

<xsd:complexContent) 

<xsd:restriction base="anb:FlowItemType") 

<xsd:attribute name="Name" type="anb:CountItemNameType" use="required"/) 
<xsd:attribute name="Value" type="anb:NumberType" use="required"/) 

</xsd:restriction) 

</xsd:complexContent) 

</xsd:complexType) 


<!-- CharactenRangeType is an extension of ContentLocatorPantType that locates 

* pant of the content within a FlowDocument. CharactenRangeType contains one 

* "Item" element with name "Count" and value the number(N) of "SegmentXX" 

* elements that this ContentLocatorPart has. It also contains N "Item" 

* elements with name "SegmentXX" where XX is a number from 0 to N-1. The 

* value of each "SegmentXX" element is a string in the form "offsetj length" 

* which locates one sequence of symbols in the FlowDocument. Example: 

* <anb:CharacterRange> 

* <anc:Item Name="Count" \/alue="2" /> 

* <anc:Item Name="Segment0" Value="5,10" /> 

* <anc:Item Name="Segmentl" Value="25j2" /> 

* </anb:CharacterRange> 

--> 

<xsd:complexType name="CharacterRangeType"> 

<xsd:complexContent> 

<xsd:extension base="anc:ContentLocatorPartType"> 

<xsd:sequence minOccurs="l" maxOccurs="unbounded"> 

<xsd:element name="Item" type="anb:FlowItemType" /> 

</xsd:sequence> 

</xsd:extension> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- CharacterRange element substitutes ContentLocatorPart element --> 

<xsd:element name="CharacterRange" type="anb:CharactenRangeType" 
substitutionGroup="anc:ContentLocatorPart"/> 

<!-- Fixed LocatorPart --> 

<!-- Flelper type - FixedItemType --> 

<xsd:complexType name="FixedItemType" abstract = "true"> 

<xsd:complexContent> 

<xsd:restriction base="anc:ItemType"> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- Flelper type - FixedCountItemType: ContentLocatorPart items count --> 

<xsd:complexType name="FixedCountItemType"> 

<xsd:complexContent> 

<xsd:restriction base="anb:FixedItemType"> 

<xsd:attribute name="Mame" type="anb:CountItemNameType" use="required"/> 
<xsd:attribute name="Value" type="anb:NumberType" use="required"/> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- Flelper type -FixedSegmentValue: Defines possible fixed segment values --> 
<xsd rsimpleType name="FixedSegmentItem\/alueType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value="\d*j\d*j\d*j\d*" /> 

</xsd:restriction> 

</xsd:simpleType> 

<1-- Flelper type - FixedSegmentItemType --> 

<xsd:complexType name="FixedSegmentItemType"> 

<xsd:complexContent> 

<xsd:restriction base="anb:FixedItemType"> 

<xsd:attribute name="Mame" use="required" 

type="anb:SegmentItemNameType"/> 

<xsd:attribute name="Value" use="required" 

type="anb:FixedSegmentItemValueType "/> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 


<1-- FixedTextRangeTvoe is an extension of ContentLocatorPartTvoe that locates 


* content within a FixedDocument. It contains one "Item" element with name 

* "Count" and value the number (IM) of "Item" elements with name "SegmentXX" 

* that this ContentLocatorPart has. FixedTextRange locator part also 

* contains N "Item" elements with one attribute Name="SegmentXX" where XX is 

* a number from 0 to N-1 and one attribute "Value" in the form "Xl, Yl, X2, 

* Y2". Flere Xl^Yl are the coordinates of the start symbol in this segment, 

* X2,Y2 are the coordinates of the end symbol in this segment. Example: 

* 

* <anb:FixedTextRange> 

* <anc:Item Name="Count" Value="2" /> 

* <anc:Item Name="Segment0" Value="10,5,20,5" /> 

* <anc:Item Name="Segmentl" Value="25,15, 25,20" /> 

* </anb:FixedTextRange> 

--> 

<xsd:complexType name="FixedTextRangeType"> 

<xsd:complexContent> 

<xsd:extension base="anc:ContentLocatorPartType"> 

<xsd:sequence minOccurs="l" maxOccurs="unbounded"> 

<xsd:element name="Item" type="anb:FixedItemType" /> 

</xsd:sequence> 

</xsd:extension> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- FixedTextRange element substitutes ContentLocatorPart element --> 

<xsd:element name="FixedTextRange" type="anb:FixedTextRangeType" 
substitutionGroup="anc:ContentLocatorPart"/> 

<!-- Datald --> 

<!-- ValueltemNameType: helper type to define value item --> 

<xsd:simpleType name="ValueItemNameType"> 

<xsd:restriction base='xsd:string'> 

<xsd:pattern value="Value" /> 

</xsd:restriction> 

</xsd:simpleType> 

<!-- StringValueltemType --> 

<xsd:complexType name="StringValueItemType"> 

<xsd:complexContent> 

<xsd:restriction base="anc:ItemType"> 

<xsd:attribute name="Name" type="anb:ValueItemNameType" use="required"/> 
<xsd:attribute name="Value" type="xsd:string" use="required"/> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 

<xsd:complexType name="StringValueLocatorPartType"> 

<xsd:complexContent> 

<xsd:extension base="anc:ContentLocatorPartType"> 

<xsd:sequence minOccurs="l" maxOccurs="l"> 

<xsd:element name="Item" type="anb:ValueItemType" /> 

</xsd:sequence> 

</xsd:extension> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- Datald element substitutes ContentLocatorPart and is used to locate a 

* subtree in the logical tree. Including Datald locator part in a 

* ContentLocator helps to narrow down the search for a particular content. 

* Example of Datald ContentLocatorPart: 

* 

* <anb:DataId> 

* <anc:Item Name="Value" Value="FlowDocument" /> 

* </anb:DataId> 

--> 

<xsd:element name="DataId" type="anb: StringValueLocatorPartType " 
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<!-- PageNumber --> 

<!-- NumberValueltemType --> 

<xsd:complexType name="MumberValueItemType"> 

<xsd:complexContent> 

<xsd:nestniction base="anc:ItemType"> 

<xsd:attribute name="Name" type="anb:ValueItemNameType" use="required"/> 
<xsd:attribute name="Value" type="anb:NumberType" use="required"/> 

</xsd:restriction> 

</xsd:complexContent> 

</xsd:complexType> 

<xsd:complexType name="MumberValueLocatorPartType"> 

<xsd:complexContent> 

<xsd:extension base="anc:ContentLocatorPartType"> 

<xsd:sequence minOccurs="l" maxOccurs="l"> 

<xsd:element name="Item" type="anb:ValueItemType" /> 

</xsd:sequence> 

</xsd:extension> 

</xsd:complexContent> 

</xsd:complexType> 

<!-- PageNumber element substitutes ContentLocatorPart and is used to locate a 

* page in a FixedDocument. PageNumber ContentLocatorPart is used in 

* conjunction with the FixedTextRange ContentLocatorPart and it shows on with 

* page are the coordinates defined in the FixedTextRange. 

* Example of a PageNumber ContentLocatorPart: 

* 

* <anb:PageNumber> 

* <anc:Item Name="\/alue" Value="l" /> 

* </anb:PageNumber> 

--> 

<xsd:element name="PageNumber" type="anb:NumberValueLocatorPartType" 
substitutionGroup="anc:ContentLocatorPart"/> 

<!-- ***** Content ***** --> 

<!-- Flighlight colors - defines highlight color for annotations of type 

* Flighlight or normal and active anchor colors for annotations of type 

* TextStickyNote and InkStickyNote. 

--> 

<xsd:complexType name="ColorsContentType"> 

<xsd:attribute name="Background" type='xsd:string' use="required" /> 

<xsd:attribute name="ActiveBackground" type='xsd:string' use="optional" /> 
</xsd:complexType> 

<xsd:element name="Colors" type="anb:ColorsContentType" 
substitutionGroup="anc:Content"/> 

<!-- RTB Text -contains XAML representing StickyNote Reach Text Box text. 

* Used in annotations of type TextStickyNote. --> 

<xsd:complexType name="TextContentType"> 

<!-- See XAML schema for RTB content --> 

</xsd:complexType> 

<xsd:element name="Text" type="anb:TextContentType" 
substitutionGroup="anc:Content"/> 

<!-- Ink - contains XAML representing Sticky Note ink. 

* Used in annotations of type InkStickyNote. --> 

<xsd:complexType name="InkContentType"> 

<!-- See XAML schema for Ink content --> 

</xsd:complexType> 

<xsd:element name="Ink" type="anb:InkContentType" 
substitutionGroup="anc:Content"/> 

<!-- SN Metadata - defines StickyNote attributes as position widths heightj 


exc. usea in annoxaxions or xype iexxbxicKyNoxe ana inKMXicKyNoxe. --> 
<xsd:complexType name="MetadataContentType"> 

<xsd:attribute name="Left" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="Top" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="Width" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="Height" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="XOffset" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="YOffset" type='xsd:decimal' use="optional" /> 

<xsd:attribute name="ZOrder" type='xsd:decimal' use="optional" /> 

</xsd:complexType> 

<xsd:element name="Metadata" type="anb:MetadataContentType" 
substitutionGroup="anc:Content"/> 

</xsd:schema) 


Sample XML Produced by Annotations XmlStreamStore 

The XML that follows shows the output of an Annotations XmlStreamStore and the organization of a sample file 
that contains three annotations - a highlight, a text sticky-note, and an ink stick-note. 

<?xml version="1.0" encoding="utf-8"?> 

<anc:Annotations 

xmlns:anc="http://schemas.microsoft.com/windows/annotations/2003/ll/core" 
xmlns:anb="http://schemas.microsoft.com/windows/annotations/2003/ll/base"> 

<anc:Annotation Id="d308ea9b-36eb-4cc4-94d0-97634fl0f7a2" 

CreationTime="2006-09-13T18:28:51.4465702-07:00" 

LastModificationTime="2006-09-13T18:28:51.4465702-07:00" 

Type="anb:Highlight"> 

<anc:Anchors) 

<anc:Resource Id="4f53661b-7328-4673-8e3f-c53f08b9cd94") 

<anc:ContentLocator) 

<anb:DataId) 

<anc:Item Name="\/alue" Value="FlowDocument" /) 

</anb:DataId) 

<anb:CharacterRange) 

<anc:Item Name="Segment0" \/alue="600j609" /) 

<anc:Item Name="Count" Value="l" /) 

</anb:CharacterRange) 

</anc:ContentLocator) 

</anc:Resource) 

</anc:Anchors) 

</anc:Annotation) 

<anc:Annotation Id="d7a8d271-387e-4144-9f8b-bc3c97816e5f" 

CreationTime="2006-09-13T18:28:56.7903202-07:00" 

LastModificationTime="2006-09-13T18:28:56.8996952-07:00" 

Type="anb:TextStickyNote") 

<anc:Authors) 

<anb:StringAuthor)Denise Smith</anb:StringAuthor) 

</anc:Authors) 

<anc:Anchors) 

<anc:Resource Id="dab2560e-6ebd-4ad0-80f9-483356a3be0b") 

<anc:ContentLocator) 

<anb:DataId) 

<anc:Item Name="\/alue" Value="FlowDocument" /) 

</anb:DataId) 

<anb:CharacterRange) 

<anc:Item Name="Segment0" \/alue="787j801" /) 

<anc:Item Name="Count" Value="l" /) 

</anb:CharacterRange) 

</anc:ContentLocator) 

</anc:Resource) 

</anc:Anchors) 


<anc:Car'gos> 

<anc:Resource Id="ea4dbabd-b400-4cf9-8908-5716b410f9e4" Name="Meta Data"> 
<anb:MetaData anb:ZOrder="0" /> 

</anc:Resource) 

</anc:Cargos> 

</anc:Annotation) 

<anc:Annotation Id="66803c69-b0d7-4cc3-bdff-caccl955e806" 

CreationTime="2006-09-13T18:29:03.6653202-07:00" 
LastModificationTime="2006-09-13T18:29:03.7121952-07:00" 
Type="anb:InkStickyNote") 

<anc:Authors) 

<anb:StringAuthor)Mike Nash</anb:StringAuthor) 

</anc:Authors) 

<anc:Anchors) 

<anc:Resource Id="52251c53-8eeb-4fd7-b8f3-94e78dfc25fa") 

<anc:ContentLocator) 

<anb:DataId) 

<anc:Item Name="\/alue" Value="FlowDocument" /) 

</anb:DataId) 

<anb:CharacterRange) 

<anc:Item Name="Segment0" \/alue="880j884" /) 

<anc:Item Name="Count" Value="l" /) 

</anb:CharacterRange) 

</anc:ContentLocator) 

</anc:Resource) 

</anc:Anchors) 

<anc:Cargos) 

<anc:Resource Id="lle50b97-8d91-4ff9-82c3-16607b2b552b" Name="Meta Data") 
<anb:MetaData anb:ZOrder="l" /) 

</anc:Resource) 

</anc:Cargos) 

</anc:Annotation) 

</anc:Annotations) 


See also 

• System.Windows.Annotations 

• System.Windows.Annotations.Storage 

• Annotation 

• AnnotationStore 

• XmlStreamStore 

• Annotations Overview 
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Flow content elements provide the building blocks for creating flow content suitable for hosting in a 
FlowDocument. 

In This Section 
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Flow documents are designed to optimize viewing and readability. Rather than being set to one predefined 
layout, flow documents dynamically adjust and reflow their content based on run-time variables such as window 
size, device resolution, and optional user preferences. In addition, flow documents offer advanced document 
features, such as pagination and columns. This topic provides an overview of flow documents and how to create 
them. 

What is a Flow Document 

A flow document is designed to "reflow content" depending on window size, device resolution, and other 
environment variables. In addition, flow documents have a number of built in features including search, viewing 
modes that optimize readability, and the ability to change the size and appearance of fonts. Flow Documents are 
best utilized when ease of reading is the primary document consumption scenario. In contrast. Fixed Documents 
are designed to have a static presentation. Fixed Documents are useful when fidelity of the source content is 
essential. See Documents in WPF for more information on different types of documents. 

The following illustration shows a sample flow document viewed in several windows of different sizes. As the 
display area changes, the content reflows to make the best use of the available space. 




Lomn ipsum dolor sit smet. consoctetuer 
sdipisdng elit. NuUa Usula tortor. daptbus et 
facUisis a. aliquet et. diain. Cras convallts. Fusee 

uma. Quisque interdum. turpis sed dictiun \ 

fringilla. magna arcu gra\nda libero. eiementum 
tincidunt dolor mauris sed erat. Curabitur 
egestas aliquet Edam quis sem in lorem 
auctor consequat. Suspendisse \itae 
Proin eleifend elemennim ligula. Donee mattis 
consectetuer Donee fermentum 

conseetetuer Suspendisse tempos 

faucibus magna. Pellentesque sodales %*elit 
Phasellus \'elit magna. malesuada 
rboncus eged dignissim ut. metus. Praesent 
pul%'mar suscipit diam. 


Lorem ipsum dolor sit amet. consectetuer 
adipiscing elit. Nulla ligula tortor, dapibus et. 
facUisis a. aliquet et. diam. Cras con\’aUis. Fusee 
at uma. Quisque interdum. turpis sed dictum 
fringilla, magna arcu granda libero, eiementum 
tincidunt dolor mauris sed erat. Curabitur 
egestas aliquet nibh. Etiam quis sem in lorem 
auctor consequat. Suspendisse \itae lorem. Proin 
eleifend eiementum ligula. Donee mattis 
consectetuer erat. Donee fermentum 
consectetuer neque. Suspendisse tempus 
faucibus magna. Pellentesque sodales ^*elit eget 
nibh. Phasellus \‘elit magna, malesuada ntae, 
rhoncus eget, dignissim ut. metus. Praesent 
puhinar suscipit diam. 
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Morbi ut tellus at tellus semper consectetuer. 
Nuliam fringilla nonummy justo. Proin rutrum, 
purus id adipiscing m^esuada. enim \elit 
accumsan nisi, pellentesque rhoncus nibh nisi 
ut magna. Nunc massa nulla, solutpat sit amet. 
pul%'inar ac. scelerisque ac. magna. Nulla 
facilisi. Integer pharetra felis xltae risus. Nunc 
aliquet lacus pretium uma \'arius hendrerit. 
Duis odio nisi, ^'enenatis at. soUicitudin eu, 
xixerra sed, nibh. Nuliam consequat. Duis felis 
felis. rutrum ^'i\'erra, auctor eget. iaculis ut, mi. 
Integer sagittis pharetra ipsum. Donee lacinla 
scelerisque nisi. Nuliam aliquet. In et sapien. 
FUsce blandit odio et mi. 
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Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Nulla ligula 
tortor, dapibus et. facilisis a. aliquet et. diam. Cras convallis. Fusee at 
uma. Quisque interdum, turpis sed dictum fringilla, magna arcu 
gra\-ida libero, eiementum tincidunt dolor mauris sed erat. Curabitur 
egestas aliquet nibh. Etiam quis sem in lorem auctor consequat. 
Suspendisse xitae lorem. Proin eleifend eiementum ligula. Donee 
mattis consectetuer erat. Donee fermentum consectetuer neque. 
Suspendisse tempus faucibus magna. Pellentesque sodales \elit eget 
nibh. Phasellus celit magna. malesuada \itae. rhoncus eget, 
dignissim ut. metus. Praesent pulxinar suscipit diam. 



Morbi ut tellus at tellus semper consectetuer. Nuliam fiingilla 
nonummy justo. Proin rutrum. purus id adipiscing malesuada. enim 
\elit accumsan nisi, pellentesque rhoncus nibh nisi ut magna. Nimc 
massa nulla, \-olutpat sit amet. puhSnar ac, scelerisque ac, magna. 
Nulla facilisi. Integer pharetra felis \itae risus. Nunc aliquet lacus 
pretium uma rarius hendrerit. Duis odio nisi, \enenatis at. 
soUicitudin eu, \iverra sed, nibh. NuUam consequat. Duis felis felis, 
rutrum \i\erra. auctor eget. iaculis ut. mi. Integer sagittis pharetra 
ipsum. Donee lacinia scelerisque nisi. Nuliam aliquet. In et sapien. 
Fusee blandit odio et mi. 

Vestibulum ante ipsum primis in faucibus orci luctus et ultrices 
posuere cubilia Curae; Suspendisse laoreet condimentum purus. 
Etiam \el enim. Suspendisse at dolor. PeUentesque gravida. ..\enean 
convallis. \'ivamus diam. Aenean lorem libero, suscipit vel, tempor 
eu, fermentum aliquam, metus. Quisque volutpat uma at augue. 
Nam placerat. In viverra congue tellus. Proin auctor. Fusee nisi 
lorem. dapibus vitae, porta sed, malesuada a, lacus. Phasellus mollis 
eiementum enim. Lorem ipsum dolor sit amet, consectetuer 
adipiscing elit. Etiam vitae uma vel velit volutpat tempor. Quisque ac 
dolor. Suspendisse potenti. Nunc nec tortor. Curabitur pharetra 
I)ellentesque diam. 
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As seen in the image above, flow content can include many components including paragraphs, lists, images, and 
more. These components correspond to elements in markup and objects in procedural code. We will go over 
these classes in detail later in the Flow Related Classes section of this overview. For now, here is a simple code 
example that creates a flow document consisting of a paragraph with some bold text and a list. 

















<!-- This simple flow document includes a paragraph with some 
bold text in it and a list. --> 

<FlowDocumentReader xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<FlowDocument> 

<Paragraph> 

<Bold>Some bold text in the paragraph.</Bold> 

Some text that is not bold. 

</Paragraph> 

<List> 

<ListItem> 

<Paragraph>ListItem 1</Paragraph> 

</ListItem> 

<ListItem> 

<Paragraph>ListItem 2</Paragraph> 

</ListItem> 

<ListItem> 

<Paragraph>ListItem 3</Paragraph> 

</ListItem> 

</Llst> 

</FlowDocument> 

</FlowDocumentReader> 



using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class SimpleFlowExample : Page 

{ 

public SimpleFlowExampleO 

{ 

Paragraph myParagraph = new Paragraph(); 

// Add some Bold text to the paragraph 

myParagraph.Inlines.Add(new Bold(new Run("Some bold text in the paragraph."))); 
// Add some plain text to the paragraph 

myParagraph.Inlines.Add(new Run(" Some text that is not bold.")); 

// Create a List and populate with three list items. 

List myList = new List(); 

// First create paragraphs to go into the list item. 

Paragraph paragraphListlteml = new Paragraph(new Run("ListItem 1")); 

Paragraph paragraphListItem2 = new Paragraph(new Run("ListItem 2")); 

Paragraph paragraphListItemB = new Paragraph(new Run("ListItem 3")); 

// Add Listitems with paragraphs in them. 
myList.ListItems.Add(new Listltem(paragraphListlteml)); 
myList.ListItems.Add(new ListItem(paragraphListItem2)); 
myList.Listitems.Add(new ListItem(paragraphListItem3)); 

// Create a FlowDocument with the paragraph and list. 

FlowDocument myFlowDocument = new FlowDocument(); 
myFlowDocument.Blocks.Add(myParagraph); 
myFlowDocument.Blocks.Add(myList); 

// Add the FlowDocument to a FlowDocumentReader Control 
FlowDocumentReader myFlowDocumentReader = new FlowDocumentReader(); 
myFlowDocumentReader.Document = myFlowDocument; 

this.Content = myFlowDocumentReader; 

} 

} 

} 



Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class SimpleFlowExample 
Inherits Page 
Public Sub New() 

Dim myParagraph As New Paragraph() 

' Add some Bold text to the paragraph 

myParagraph.Inlines.Add(New Bold(New Run("Some bold text in the paragraph."))) 
' Add some plain text to the paragraph 

myParagraph.Inlines.Add(New Run(" Some text that is not bold.")) 

' Create a List and populate with three list items. 

Dim myList As New List() 

' First create paragraphs to go into the list item. 

Dim paragraphListlteml As New Paragraph(New Run("ListItem 1")) 

Dim paragraphListItem2 As New Paragraph(New Run("ListItem 2")) 

Dim paragraphListItemB As New Paragraph(New Run("ListItem 3")) 

' Add Listitems with paragraphs in them. 
myList.Listitems.Add(New Listltem(paragraphListlteml)) 
myList.Listitems.Add(New ListItem(paragraphListItem2)) 
myList.ListItems.Add(New ListItem(paragraphListItem3)) 

' Create a FlowDocument with the paragraph and list. 

Dim myFlowDocument As New FlowDocument() 
myFlowDocument.Blocks.Add(myParagraph) 
myFlowDocument.Blocks.Add(myList) 

' Add the FlowDocument to a FlowDocumentReader Control 
Dim myFlowDocumentReader As New FlowDocumentReader() 
myFlowDocumentReader.Document = myFlowDocument 

Me.Content = myFlowDocumentReader 
End Sub 
End Class 
End Namespace 


The illustration below shows what this code snippet looks like. 


Some bold text in the paragraph. Some text that is not bold 

• Listitem 1 

• Listitem 2 

• Listitem 3 
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In this example, the FlowDocumentReader control is used to host the flow content. See Flow Document Types for 
more information on flow content hosting controls. Paragraph, List, Listitem, and Bold elements are used to 
control content formatting, based on their order in markup. For example, the Bold element spans across only 
part of the text in the paragraph; as a result, only that part of the text is bold. If you have used HTML, this will be 
familiar to you. 












As highlighted in the illustration above, there are several features built into Flow Documents: 

• Search: Allows the user to perform a full text search of an entire document. 

• Viewing Mode: The user can select their preferred viewing mode including a single-page (page-at-a-time) 
viewing mode, a two-page-at-a-time (book reading format) viewing mode, and a continuous scrolling 
(bottomless) viewing mode. For more information about these viewing modes, see 
FlowDocumentReaderViewingMode. 

• Page Navigation Controls: If the viewing mode of the document uses pages, the page navigation controls 
include a button to jump to the next page (the down arrow) or previous page (the up arrow), as well as 
indicators for the current page number and total number of pages. Flipping through pages can also be 
accomplished using the keyboard arrow keys. 

• Zoom: The zoom controls enable the user to increase or decrease the zoom level by clicking the plus or 
minus buttons, respectively. The zoom controls also include a slider for adjusting the zoom level. For more 
information, see Zoom. 

These features can be modified based upon the control used to host the flow content. The next section describes 
the different controls. 

Flow Document Types 

Display of flow document content and how it appears is dependent upon what object is used to host the flow 
content. There are four controls that support viewing of flow content: FlowDocumentReader, 
FlowDocumentPageViewer, RichTextBox, and FlowDocumentScrollViewer. These controls are briefly described 
below. 


NOTE 

FlowDocument is required to directly host flow content, so all of these viewing controls consume a FlowDocument to 
enable flow content hosting. 


FlowDocumentReader 

FlowDocumentReader includes features that enable the user to dynamically choose between various viewing 
modes, including a single-page (page-at-a-time) viewing mode, a two-page-at-a-time (book reading format) 
viewing mode, and a continuous scrolling (bottomless) viewing mode. For more information about these 
viewing modes, see FlowDocumentReaderViewingMode. If you do not need the ability to dynamically switch 
between different viewing modes, FlowDocumentPageViewer and FlowDocumentScrollViewer provide lighter- 
weight flow content viewers that are fixed in a particular viewing mode. 

FlowDocumentPageViewer and FlowDocumentScrollViewer 

FlowDocumentPageViewer shows content in page-at-a-time viewing mode, while FlowDocumentScrollViewer 
shows content in continuous scrolling mode. Both FlowDocumentPageViewer and FlowDocumentScrollViewer 
are fixed to a particular viewing mode. Compare to FlowDocumentReader, which includes features that enable 
the user to dynamically choose between various viewing modes (as provided by the 
FlowDocumentReaderViewingMode enumeration), at the cost of being more resource intensive than 
FlowDocumentPageViewer or FlowDocumentScrollViewer. 

By default, a vertical scrollbar is always shown, and a horizontal scrollbar becomes visible if needed. The default 
Ul for FlowDocumentScrollViewer does not include a toolbar; however, the IsToolBarVisible property can be used 
to enable a built-in toolbar. 

RichTextBox 

You use a RichTextBox when you want to allow the user to edit flow content. For example, if you wanted to create 



an editor that allowed a user to manipulate things like tables, italic and bold formatting, etc, you would use a 
RichTextBox. See RichTextBox Overview for more information. 


NOTE 

Flow content inside a RichTextBox does not behave exactly like flow content contained in other controls. For example, there 
are no columns in a RichTextBox and hence no automatic resizing behavior. Also, the typically built in features of flow 
content like search, viewing mode, page navigation, and zoom are not available within a RichTextBox. 


Creating Flow Content 

Flow content can be complex, consisting of various elements including text, images, tables, and even UlElement 

derived classes like controls. To understand how to create complex flow content, the following points are critical: 

• Flow-related Classes: Each class used in flow content has a specific purpose. In addition, the 
hierarchical relation between flow classes helps you understand how they are used. For example, classes 
derived from the Block class are used to contain other objects while classes derived from Inline contain 
objects that are displayed. 

• Content Schema: A flow document can require a substantial number of nested elements. The content 
schema specifies possible parent/child relationships between elements. 

The following sections will go over each of these areas in more detail. 

Flow Related Classes 

The diagram below shows the objects most typically used with flow content: 
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For the purposes of flow content, there are two important categories: 

1. Block-derived classes: Also called "Block content elements" or just "Block Elements". Elements that 
inherit from Block can be used to group elements under a common parent or to apply common attributes 
to a group. 

2. Inline-derived classes: Also called "Inline content elements" or just "Inline Elements". Elements that 
inherit from Inline are either contained within a Block Element or another Inline Element. Inline Elements 
are often used as the direct container of content that is rendered to the screen. For example, a Paragraph 
(Block Element) can contain a Run (Inline Element) but the Run actually contains the text that is rendered 
on the screen. 

Each class in these two categories is briefly described below. 



Block-derived Classes 
Paragraph 

Paragraph is typically used to group content into a paragraph. The simplest and most common use of Paragraph 
is to create a paragraph of text. 

<FlowDocument xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<Paragraph> 

Some paragraph text. 

</Paragraph> 

</FlowDocument> 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class ParagraphExample : Page 

{ 

public ParagraphExampleO 

{ 

// Create paragraph with some text. 

Paragraph myParagraph = new Paragraph(); 

myParagraph.Inlines.Add(new Run("Some paragraph text.")); 

// Create a ElowDocument and add the paragraph to it. 
ElowDocument myFlowDocument = new FlowDocument(); 
myElowDocument.Blocks.Add(myParagraph); 

this.Content = myFlowDocument; 

} 

} 

} 


Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class ParagraphExample 
Inherits Page 
Public Sub New() 

' Create paragraph with some text. 

Dim myParagraph As New Paragraph() 

myParagraph.Inlines.Add(New Run("Some paragraph text.")) 

' Create a ElowDocument and add the paragraph to it. 

Dim myFlowDocument As New ElowDocument() 
myFlowDocument.Blocks.Add(myParagraph) 

Me.Content = myFlowDocument 
End Sub 
End Class 
End Namespace 


However, you can also contain other inline-derived elements as you will see below. 



Section 


Section is used only to contain other Block-derived elements. It does not apply any default formatting to the 
elements it contains. However, any property values set on a Section applies to its child elements. A section also 
enables you to programmatically iterate through its child collection. Section is used in a similar manner to the 
<DIV> tag in HTML. 

In the example below, three paragraphs are defined under one Section. The section has a Background property 
value of Red, therefore the background color of the paragraphs is also red. 

<FlowDocument xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml"> 

<!-- By defaultj Section applies no formatting to elements contained 
within it. Howeverj in this example^ the section has a Background 
property value of "Red"^ therefore, the three paragraphs (the block) 
inside the section also have a red background. --> 

<Section Background="Red"> 

<Paragraph> 

Paragraph 1 
</Paragraph> 

<Paragraph> 

Paragraph 2 
</Paragraph> 

<Paragraph> 

Paragraph 3 
</Paragraph> 

</Section> 

</FlowDocument> 


using System; 
using System.Windows; 
using System.Windows.Media; 
using System.Windows.Controls; 
using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class SectionExample : Page 

{ 

public SectionExample() 

{ 

// Create three paragraphs 

Paragraph myParagraphl = new Paragraph(new Run("Paragraph 1")); 

Paragraph myParagraph2 = new Paragraph(new Run("Paragraph 2")); 

Paragraph myParagraphB = new Paragraph(new Run("Paragraph 3")); 

// Create a Section and add the three paragraphs to it. 

Section mySection = new Section(); 
mySection.Background = Brushes.Red; 

mySection.Blocks.Add(myParagraphl); 
mySection.Blocks.Add(myParagraph2); 
mySection.Blocks.Add(myParagraphs); 

// Create a FlowDocument and add the section to it. 

FlowDocument myFlowDocument = new FlowDocument(); 
myFlowDocument.Blocks.Add(mySection); 

this.Content = myFlowDocument; 

} 

} 

} 



Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class SectionExample 
Inherits Page 
Public Sub New() 

' Create three paragraphs 

Dim myParagraphl As New Paragraph(New Run("Paragraph 1")) 
Dim myParagraph2 As New Paragraph(New Run("Paragraph 2")) 
Dim myParagraphB As New Paragraph(New Run("Paragraph 3")) 

' Create a Section and add the three paragraphs to it. 

Dim mySection As New Section() 
mySection.Background = Brushes.Red 

mySection.Blocks.Add(myParagraphl) 
mySection.Blocks.Add(myParagraph2) 
mySection.Blocks.Add(myParagraphs) 

' Create a FlowDocument and add the section to it. 

Dim myFlowDocument As New FlowDocument() 
myFlowDocument.Blocks.Add(mySection) 

Me.Content = myFlowDocument 
End Sub 
End Class 
End Namespace 


BlockUIContainer 

BlockUIContainer enables UlElement elements (i.e. a Button) to be embedded in block-derived flow content. 
InlineUIContainer (see below) is used to embed UlElement elements in inline-derived flow content. 
BlockUIContainer and InlineUIContainer are important because there is no other way to use a UlElement in flow 
content unless it is contained within one of these two elements. 

The following example shows how to use the BlockUIContainer element to host UlElement objects within flow 


content. 



< FlowDocument ColumnWidth="400"> 

<Section Background="GhostWhite"> 

<Par'agraph> 

A UIElement element may be embedded directly in flow content 
by enclosing it in a BlockUIContainer element. 

</Paragraph> 

<BlockUIContainer> 

<Button>Click me!</Button> 

</BlockUIContainer> 

<Paragraph> 

The BlockUIContainer element may host no more than one top-level 
UIElement. Howeverj other UIElements may be nested within the 
UIElement contained by an BlockUIContainer element. For examplOj 
a StackPanel can be used to host multiple UIElement elements within 
a BlockUIContainer element. 

</Paragraph> 

<BlockUIContainer> 

<StackPanel> 

<Label Foreground="Blue">Choose a value:</Label> 

<ComboBox> 

<ComboBoxItem IsSelected="True">a</ComboBoxItem> 
<ComboBoxItem>b</ComboBoxItem> 

<ComboBoxItem>c</ComboBoxItem> 

</ComboBox> 

<Label Foreground ="Red">Choose a value:</Label> 

<StackPanel> 

<RadioButton>x</RadioButton> 

<RadioButton>y</RadioButton> 

<RadioButton>z</RadioButton> 

</StackPanel> 

<Label>Enter a value:</Label> 

<TextBox> 

A text editor embedded in flow content. 

</TextBox> 

</StackPanel> 

</BlockUIContainer> 

</Section> 

</FlowDocument> 


The following figure shows how this example renders: 

A UIElement element may be embedded directly in flow content by enclosing it 
in a BlockUIContainer element. 


Click me! 


The BlockUIContainer element may host no more than one top-level UIElement. 
However, other UIElements may be nested within the UIElement contained by 
an BlockUIContainer element. For example, a StackPanel can be used to host 
multiple UIElement elements within a BlockUIContainer element. 
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Enter a value: 


A text editor embedded in flow content. 


List 

List is used to create a bulleted or numeric list. Set the MarkerStyle property to a TextMarkerStyle enumeration 
value to determine the style of the list. The example below shows how to create a simple list. 







<FlowDocument xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<List> 

<ListItem> 

<Paragraph> 

List Item 1 
</Paragraph> 

</ListItem> 

<ListItem> 

<Paragraph> 

List Item 2 
</Paragraph> 

</ListItem> 

<ListItem> 

<Paragraph> 

List Item 3 
</Paragraph> 

</ListItem> 

</List> 

</FlowDocument> 


using System; 
using System.Windows; 
using System.Windows.Media; 
using System.Windows.Controls; 
using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class ListExample : Page 

{ 

public ListExampleO 

{ 

// Create three paragraphs 

Paragraph myParagraphl = new Paragraph(new Run("List Item 1")); 

Paragraph myParagraph2 = new Paragraph(new Run("List Item 2")); 

Paragraph myParagraphB = new Paragraph(new Run("List Item 3")); 

// Create the Listitem elements for the List and add the 

// paragraphs to them. 

Listitem myListlteml = new Listltem(); 
myListIteml.Blocks.Add(myParagraphl); 

Listitem myListItem2 = new Listltem(); 
myListItem2.Blocks.Add(myParagraph2); 

Listitem myListItem3 = new Listltem(); 
myListItem3.Blocks.Add(myParagraph3); 

// Create a List and add the three Listitems to it. 

List myList = new List(); 

myList.ListItems.Add(myListIteml); 
myList.Listitems.Add(myListltem2); 
myList.Listitems.Add(myListltem3); 

// Create a FlowDocument and add the section to it. 

FlowDocument myFlowDocument = new FlowDocument(); 
myFlowDocument.Blocks.Add(myList); 

this.Content = myFlowDocument; 

} 

} 

} 



Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class ListExample 
Inherits Page 
Public Sub New() 

' Create three paragraphs 

Dim myParagraphl As New Paragraph(New Run("List Item 1")) 

Dim myParagraph2 As New Paragraph(New Run("List Item 2")) 

Dim myParagraphB As New Paragraph(New Run("List Item 3")) 

' Create the Listitem elements for the List and add the 
' paragraphs to them. 

Dim myListlteml As New Listltem() 
myListIteml.Blocks.Add(myParagraphl) 

Dim myListItem2 As New Listltem() 
myListItem2.Blocks.Add(myParagraph2) 

Dim myListItemB As New Listltem() 
myListItemB.Blocks.Add(myParagraphs) 

' Create a List and add the three Listitems to it. 

Dim myList As New List() 

myList.Listitems.Add(myListlteml) 
myList. List Items. Add (my List Item2) 
myList. List Items. Add (my List Items) 

' Create a FlowDocument and add the section to it. 

Dim myPlowDocument As New FlowDocument() 
myFlowDocument.Blocks.Add(myList) 

Me.Content = myFlowDocument 
Fnd Sub 
Fnd Class 
Fnd Namespace 


NOTE 

List is the only flow element that uses the ListItemCollection to manage child elements. 


Table 

Table is used to create a table. Table is similar to the Grid element but it has more capabilities and, therefore, 
requires greater resource overhead. Because Grid is a UlElement, it cannot be used in flow content unless it is 
contained in a BlockUIContainer or InlineUIContainer. For more information on Table, see Table Overview. 

Inline-derived Classes 
Run 

Run is used to contain unformatted text. You might expect Run objects to be used extensively in flow content. 
However, in markup. Run elements are not required to be used explicitly. Run is required to be used when 
creating or manipulating flow documents by using code. For example, in the markup below, the first Paragraph 
specifies the Run element explicitly while the second does not. Both paragraphs generate identical output. 




<Paragraph> 

<Run>Par'agraph that explicitly uses the Run element.</Run> 
</Paragnaph> 

<Paragraph> 

This Paragraph omits the Run element in markup. It renders 
the same as a Paragraph with Run used explicitly. 
</Paragraph> 


NOTE 

Starting in the .NET Framework 4, the Text property of the Run object is a dependency property. You can bind the Text 
property to a data source, such as a TextBlock. The Text property fully supports one-way binding. The Text property also 
supports two-way binding, except for RichTextBox. For an example, see Run.Text. 


Span 

Span groups other inline content elements together. No inherent rendering is applied to content within a Span 
element. However, elements that inherit from Span including Hyperlink, Bold, Italic and Underline do apply 
formatting to text. 

Below is an example of a Span being used to contain inline content including text, a Bold element, and a Button. 

cFlowDocument xmlns="http://schemas.micr'osoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml"> 

<Panagraph> 

Text before the Span. <Span Background="Red">Text within the Span is 
red and <Bold>this text is inside the Span-derived element Bold.</Bold> 

A Span can contain more then textj it can contain any inline content. For 

example^ it can contain a 

<InlineUIContainer> 

<Button>Button</Buttons 
</InlineUIContainer> 

or other UIElement^ a Floater^ a Figure, etc.</Span> 

</Paragraph> 

</FlowDocument> 


The following screenshot shows how this example renders. 



InlineUIContainer 

InlineUIContainer enables UlElement elements (i.e. a control like Button) to be embedded in an Inline content 
element. This element is the inline equivalent to BlockUIContainer described above. Below is an example that 
uses InlineUIContainer to insert a Button inline in a Paragraph. 









<FlowDocument xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<Paragraph> 

Text to precede the button... 

<!-- Set the BaselineAlignment property to "Bottom" 

so that the Button aligns properly with the text. --> 
<InlineUIContainer BaselineAlignment="Bottom"> 

<Button>Button</Button) 

</InlineLIIContainer> 

Text to follow the button... 

</Paragraph> 

</FlowDocument> 


using System; 
using System.Windows; 
using System.Windows.Media; 
using System.Windows.Controls; 
using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class InlineUIContainerExample : Page 

{ 

public InlineUIContainerExample() 

{ 

Run runl = new Run(" Text to precede the button... "); 

Run run2 = new Run(" Text to follow the button... "); 

// Create a new button to be hosted in the paragraph. 

Button myButton = new Button(); 
myButton.Content = "Click me!"; 

// Create a new InlineUIContainer to contain the Button. 
InlineUIContainer myInlineUIContainer = new InlineUIContainer(); 

// Set the BaselineAlignment property to "Bottom" so that the 
// Button aligns properly with the text. 

myInlineUIContainer.BaselineAlignment = BaselineAlignment.Bottom; 

// Asign the button as the UI container's child. 
myInlineUIContainer.Child = myButton; 

// Create the paragraph and add content to it. 

Paragraph myParagraph = new Paragraph(); 
myParagraph.Inlines.Add(runl); 
myParagraph.Inlines.Add(myInlineUIContainer); 
myParagraph.Inlines.Add(run2); 

// Create a FlowDocument and add the paragraph to it. 

FlowDocument myFlowDocument = new FlowDocument(); 
myFlowDocument.Blocks.Add(myParagraph); 

this.Content = myFlowDocument; 

} 

} 

} 



Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class InlineUIContainerExample 
Inherits Page 
Public Sub New() 

Dim runl As New Run(" Text to precede the button... ") 

Dim run2 As New Run(" Text to follow the button... ") 

' Create a new button to be hosted in the paragraph. 

Dim myButton As New Button() 
myButton.Content = "Click me!" 

' Create a new InlineUIContainer to contain the Button. 

Dim myInlineUIContainer As New InlineUIContainer() 

' Set the BaselineAlignment property to "Bottom" so that the 
' Button aligns properly with the text. 

myInlineUIContainer.BaselineAlignment = BaselineAlignment.Bottom 

' Asign the button as the UI container's child. 
myInlineUIContainer.Child = myButton 

' Create the paragraph and add content to it. 

Dim myParagraph As New Paragraph() 
myParagraph.Inlines.Add(runl) 
myParagraph.Inlines.Add(mylnlineUIContainer) 
myParagraph.Inlines.Add(run2) 

' Create a FlowDocument and add the paragraph to it. 

Dim myPlowDocument As New FlowDocument() 
myFlowDocument.Blocks.Add(myParagraph) 

Me.Content = myFlowDocument 
End Sub 
End Class 
End Namespace 


NOTE 

InlineUIContainer does not need to be used explicitly in markup. If you omit it, an InlineUIContainer will be created 
anyway when the code is compiled. 


Figure and Floater 

Figure and Floater are used to embed content in Flow Documents with placement properties that can be 
customized independent of the primary content flow. Figure or Floater elements are often used to highlight or 
accentuate portions of content, to host supporting images or other content within the main content flow, or to 
inject loosely related content such as advertisements. 

The following example shows how to embed a Figure into a paragraph of text. 




<FlowDocument xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<Paragraph> 

<Figure 

Width="300" Height="100" 

Background="GhostWhite" FlorizontalAnchor="PageLeft" > 

<Paragraph FontStyle="Italic" Bacl<ground="Beige" Foreground="DarkGreen" > 

A Figure embeds content into flow content with placement properties 
that can be customized independently from the primary content flow 
</Paragraph> 

</Flgure> 

Lorem ipsum dolor sit amet^ consectetuer adipiscing elitj sed diam nonummy 
nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi 
enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis 
nisi ut aliquip ex ea commodo consequat. Duis autem vel eum iriure. 
</Paragraph> 

</FlowDocument> 



using System; 
using System.Windows; 
using System.Windows.Media; 
using System.Windows.Controls; 
using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class FigureExample : Page 

{ 

public FigureExampleO 

{ 

// Create strings to use as content. 

string strFigure = "A Figure embeds content into flow content with" + 

" placement properties that can be customized" + 

" independently from the primary content flow"; 
string Strother = "Lorem ipsum dolor sit amet, consectetuer adipiscing" + 

" elitj sed diam nonummy nibh euismod tincidunt ut laoreet" + 

" dolore magna aliquam erat volutpat. Ut wisi enim ad" + 

" minim veniam^ quis nostrud exerci tation ullamcorper" + 

" suscipit lobortis nisi ut aliquip ex ea commodo consequat." + 
" Duis autem vel eum iriure."; 

// Create a Figure and assign content and layout properties to it. 

Figure myFigure = new Figure(); 
myFigure.Width = new FigureLength(300); 
myFigure.Fleight = new FigureLength(100); 
myFigure.Background = Brushes.GhostWhite; 

myFigure.FlorizontalAnchor = FigureFlorizontalAnchor.PageLeft; 

Paragraph myFigureParagraph = new Paragraph(new Run(strFigure)); 
myFigureParagraph.FontStyle = FontStyles.Italic; 
myFigureParagraph.Background = Brushes.Beige; 
myFigureParagraph.Foreground = Brushes.DarkGreen; 
myFigure.Blocks.Add(myFigureParagraph); 

// Create the paragraph and add content to it. 

Paragraph myParagraph = new Paragraph(); 
myParagraph.Inlines.Add(myFigure); 
myParagraph.Inlines.Add(new Run(strOther)); 

// Create a FlowDocument and add the paragraph to it. 

FlowDocument myFlowDocument = new FlowDocument(); 
myFlowDocument.Blocks.Add(myParagraph); 

this.Content = myFlowDocument; 

} 

} 

} 





Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class FigureExample 
Inherits Page 
Public Sub New() 

' Create strings to use as content. 

Dim strFigure As String = "A Figure embeds content into flow content with" & " placement 
properties that can be customized" & " independently from the primary content flow" 

Dim Strother As String = "Lorem ipsum dolor sit ametj consectetuer adipiscing" & " elit^ sed 
diam nonummy nibh euismod tincidunt ut laoreet" & " dolore magna aliquam erat volutpat. Ut wisi enim ad" & 
minim veniam^ quis nostrud exerci tation ullamcorper" & " suscipit lobortis nisi ut aliquip ex ea commodo 
consequat." & " Duis autem vel eum iriure." 

' Create a Figure and assign content and layout properties to it. 

Dim myFigure As New Figure() 
myFigure.Width = New FigureLength(300) 
myFigure.Fleight = New FigureLength(100) 
myFigure.Background = Brushes.GhostWhite 

myFigure.FlorizontalAnchor = FigureFlorizontalAnchor.PageLeft 
Dim myFigureParagraph As New Paragraph(New Run(strFigure)) 
myFigureParagraph.FontStyle = FontStyles.Italic 
myFigureParagraph.Background = Brushes.Beige 
myFigureParagraph.Foreground = Brushes.DarkGreen 
myFigure.Blocks.Add(myFigureParagraph) 

' Create the paragraph and add content to it. 

Dim myParagraph As New Paragraph() 
myParagraph.Inlines.Add(myFigure) 
myParagraph.Inlines.Add(New Run(strOther)) 

' Create a FlowDocument and add the paragraph to it. 

Dim myFlowDocument As New FlowDocument() 
myFlowDocument.Blocks.Add(myParagraph) 

Me.Content = myFlowDocument 
End Sub 
End Class 
End Namespace 


The following illustration shows how this example renders. 

A Figure embeds content into Primary content flow text . 
flow content with placement r -.- ^ . 

properties that can be I ' 1 

customized independently from - - -r-_ 4 

the primary content flow : , . . 


Figure and Floater differ in several ways and are used for different scenarios. 

Figure; 

• Can be positioned: You can set its horizontal and vertical anchors to dock it relative to the page, content, 
column or paragraph. You can also use its Horizontal Offset and VerticalOffset properties to specify 
arbitrary offsets. 

• Is sizable to more than one column: You can set Figure height and width to multiples of page, content or 
column height or width. Note that in the case of page and content, multiples greater than 1 are not 
















allowed. For example, you can set the width of a Figure to be "0.5 page" or "0.25 content" or "2 Column". 

You can also set height and width to absolute pixel values. 

• Does not paginate; If the content inside a Figure does not fit inside the Figure, it will render whatever 
content does fit and the remaining content is lost 

Floater; 

• Cannot be positioned and will render wherever space can be made available for it. You cannot set the 
offset or anchor a Floater. 

• Cannot be sized to more than one column: By default. Floater sizes at one column. It has a Width property 
that can be set to an absolute pixel value, but if this value is greater than one column width it is ignored 
and the floater is sized at one column. You can size it to less than one column by setting the correct pixel 
width, but sizing is not column-relative, so "0.5Column" is not a valid expression for Floater width. Floater 
has no height property and it's height cannot be set, it's height depends on the content 

• Floater paginates: If its content at its specified width extends to more than 1 column height, floater breaks 
and paginates to the next column, the next page, etc. 

Figure is a good place to put standalone content where you want to control the size and positioning, and are 

confident that the content will fit in the specified size. Floater is a good place to put more free-flowing content 

that flows similar to the main page content, but is separated from it. 

LineBreak 

LineBreak causes a line break to occur in flow content. The following example demonstrates the use of LineBreak. 

<FlowDocument xmlns="http://schemas .micnosoft. com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml"> 

<Panagnaph> 

Before the LineBreak in Paragraph. 

cLineBreak /> 

After the LineBreak in Paragraph. 

<LineBreak/><LineBreak/> 

After two LineBreaks in Paragraph. 

</Paragraph> 

<Paragraph> 

<LineBreak/> 

</Paragraph> 

<Paragraph> 

After a Paragraph with only a LineBreak in it. 

</Paragraph> 

</FlowDocument> 


The following screenshot shows how this example renders. 


Before the LineBreak in Paragraph. 
After the LineBreak in Paragraph. 

After two LineBreaks in Paragraph. 


^ After a Paragraph with only a LineBreak in it. ^ 


Flow Collection Elements 

In many of the examples above, the BlockCollection and InlineCollection are used to construct flow content 
programmatically. For example, to add elements to a Paragraph, you can use the syntax: 






myParagraph.Inlines.Add(new Run("Some text")); 


This adds a Run to the InlineCollection of the Paragraph. This is the same as the implicit Run found inside a 
Paragraph in markup: 


<Paragraph> 
Some Text 
</Paragnaph> 


As an example of using the BlockCollection, the following example creates a new Section and then uses the Add 
method to add a new Paragraph to the Section contents. 

Section secx = new Section(); 

secx.Blocks.Add(new Paragnaph(new Run("A bit of text content..."))); 


Dim secx As New Section() 

secx.Blocks.Add(New Paragnaph(New Run("A bit of text content..."))) 

In addition to adding items to a flow collection, you can remove items as well. The following example deletes the 
last Inline element in the Span. 

spanx.Inlines.Remove(spanx.Inlines.Lastinline); 

spanx.Inlines.Remove(spanx.Inlines.Lastinline) 

The following example clears all of the contents (Inline elements) from the Span. 

spanx.Inlines.Clear (); 

spanx.Inlines.Clear() 

When working with flow content programmatically, you will likely make extensive use of these collections. 

Whether a flow element uses an InlineCollection (Inlines) or BlockCollection (Blocks) to contain its child elements 
depends on what type of child elements (Block or Inline) can be contained by the parent. Containment rules for 
flow content elements are summarized in the content schema in the next section. 


NOTE 

There is a third type of collection used with flow content, the ListItemCollection, but this collection is only used with a List. 
In addition, there are several collections used with Table. See Table Overview for more information. 


Content Schema 

Given the number of different flow content elements, it can be overwhelming to keep track of what type of child 
elements an element can contain. The diagram below summarizes the containment rules for flow elements. The 
arrows represent the possible parent/child relationships. 
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As can be seen from the diagram above, the children allowed for an element are not necessarily determined by 
whether it is a Block element or an Inline element. For example, a Span (an Inline element) can only have Inline 
child elements while a Figure (also an Inline element) can only have Block child elements. Therefore, a diagram is 
useful for quickly determining what element can be contained in another. As an example, let's use the diagram to 
determine how to construct the flow content of a RichTextBox. 

1. A RichTextBox must contain a FlowDocument which in turn must contain a Block-derived object. Below is the 
corresponding segment from the diagram above. 

SInglePageViewer A I 

> FlowDocument 
RichTextBox A | ^ 

Block-derived Classes P 


Thus far, this is what the markup might look like. 

<RichTextBox> 

<FlowDocument> 

<!-- One or more Block-derived object... --> 
</FlowDocument> 

</RichTextBox> 


2. According to the diagram, there are several Block elements to choose from including Paragraph, Section, 
Table, List, and BlockUIContainer (see Block-derived classes above). Let's say we want a Table. According to the 
diagram above, a Table contains a TableRowGroup containing TableRow elements, which contain TableCell 
elements which contain a Block-derived object. Below is the corresponding segment for Table taken from the 
diagram above. 

Table P—►TableRowGroup —►TableRow —►TableCell 

Block-derived Classes p 


Below is the corresponding markup. 



















<RichTextBox> 

<FlowDocument> 

<Table> 

<TableRowGroup> 

<TableRow> 

<TableCell> 

<!-- One or more Block-derived object... --> 
</TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 

</RichTextBox> 


3. Again, one or more Block elements are required underneath a TableCell. To make it simple, let's place some 
text inside the cell. We can do this using a Paragraph with a Run element. Below is the corresponding segments 
from the diagram showing that a Paragraph can take an Inline element and that a Run (an Inline element) can 
only take plain text. 
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Below is the entire example in markup. 

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<RichTextBox> 

<FlowDocument> 

<!-- Normally a table would have multiple rows and multiple 
cells but this code is for demonstration purposes.--> 

<Table> 

<TableRowGroup> 

<TableRow> 

<TableCell> 

<Paragraph> 

<!-- The schema does not actually require 

explicit use of the Run tag in markup. It 
is only included here for clarity. --> 
<Run>Paragraph in a Table Cell.</Run> 

</Paragraph> 

</TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 

</RichTextBox> 

</Page> 


Customizing Text 

Usually text is the most prevalent type of content in a flow document. Although the objects introduced above can 
be used to control most aspects of how text is rendered, there are some other methods for customizing text that 
is covered in this section. 











Text Decorations 

Text decorations allow you to apply the underline, overline, baseline, and strikethrough effects to text (see 
pictures below). These decorations are added using the TextDecorations property that is exposed by a number of 
objects including Inline, Paragraph, TextBlock, and TextBox. 

The following example shows how to set the TextDecorations property of a Paragraph. 

<FlowDocument ColumnWidth="200"> 

<Paragraph TextDecorations="Strikethrough"> 

This text will render with the strikethrough effect. 

</Paragraph> 

</FlowDocument> 


Paragraph parx = new Paragraph(new Run("This text will render with the strikethrough effect.")); 
parx.TextDecorations = TextDecorations.Strikethrough; 


Dim parx As New Paragraph(New Run("This text will render with the strikethrough effect.")) 
parx.TextDecorations = TextDecorations.Strikethrough 


The following figure shows how this example renders. 


This text will render v>ith the 

default strikethrough effect. 


The following figures show how the Overline, Baseline, and Underline decorations render, respectively. 


This text will render w ith the 
default overline effect. 


This text will render with the 

default baseline effect. 


This text will render with the 

default underline effect. 


Typography 

The Typography property is exposed by most flow-related content including TextElement, FlowDocument, 
TextBlock, and TextBox. This property is used to control typographical characteristics/variations of text (i.e. small 
or large caps, making superscripts and subscripts, etc). 

The following example shows how to set the Typography attribute, using Paragraph as the example element. 















<Paragraph 

TextAlignment="Left" 

FontSlze="18" 

FontFamily="Palatino Linotype" 

Typography.MumenalStyle="01dStyle" 

Typography. Fraction="Stacl<ed" 

Typography.Variants="Inferior" 

> 

<Run> 

This text has some altered typography characteristics. Note 
that use of an open type font is necessary for most typographic 
properties to be effective. 

</Run> 

cLineBreak/xLineBreak/x 

<Run> 

0123456789 10 11 12 13 
</Run> 

<LineBreak/><LineBreak/> 

<Run> 

1/2 2/3 3/4 
</Run> 

</Paragraph> 


The following figure shows how this example renders. 


"^his text has some altered t\-pography characteristics, ^ote that use 
of an open t\'pe font is necessary* for most h.'pographic properties to 
be elective. 


012345678910111213 


2 3 
T I 


In contrast, the following figure shows how a similar example with default typographic properties renders. 

This text has some altered typography 
characteristics. Note that use of an open tvpe font is 
necessary for most typographic properties to be 
effective. 

0123456789 10 1112 13 
1/2 2/3 3/4 


The following example shows how to set the Typography property programmatically. 





Paragraph par = new Paragraph(); 

Run runText = new Run( 

"This text has some altered typography characteristics. Note" + 
"that use of an open type font is necessary for most typographic" + 
"properties to be effective."); 

Run runNumerals = new Run("0123456789 10 11 12 13"); 

Run runfractions = new Run("l/2 2/3 3/4"); 

par.Inlines.Add(runText); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(runNumerals); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(runTractions); 

par.TextAlignment = TextAlignment.Left; 
par.FontSize = 18; 

par.FontPamily = new FontFamilyC’Palatino Linotype"); 

par.Typography.NumeralStyle = FontNumeralStyle.OldStyle; 
par.Typography.Fraction = FontFraction.Stacked; 
par.Typography.Variants = FontVariants.Inferior; 


Dim par As New Paragraph() 

Dim runText As New Run("This text has some altered typography characteristics. Note" & "that use of an open 
type font is necessary for most typographic" & "properties to be effective.") 

Dim runNumerals As New Run("0123456789 10 11 12 13") 

Dim runfractions As New Run("l/2 2/3 3/4") 

par.Inlines.Add(runText) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(runNumerals) 
par.Inllnes.Add(New LineBreak()) 
par.Inllnes.Add(New LineBreak()) 
par.Inlines.Add(runFractions) 

par.TextAlignment = TextAlignment.Left 
par.FontSize = 18 

par.FontFamily = New FontFamilyC'Palatino Linotype") 

par.Typography.NumeralStyle = FontNumeralStyle.OldStyle 
par.Typography.Fraction = FontFraction.Stacked 
par.Typography.Variants = FontVariants.Inferior 


See Typography in WPF for more information on typography. 

See also 

• Text 

• Typography in WPF 

• How-to Topics 

• TextElement Content Model Overview 

• RichTextBox Overview 

• Documents in WPF 

• Table Overview 

• Annotations Overview 




TextElement Content Model Overview 

3/12/2020 • 4 minutes to read ^ Edit Online 


This content model overview describes the supported content for a TextElement. The Paragraph class is a type of 
TextElement. A content model describes what objects/elements can be contained in others. This overview 
summarizes the content model used for objects derived from TextElement. For more information, see Flow 
Document Overview. 


Content Model Diagram 


The following diagram summarizes the content model for classes derived from TextElement as well as how other 
non- TextElement classes fit into this model. 
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As can be seen from the preceding diagram, the children allowed for an element are not necessarily determined by 
whether a class is derived from the Block class or an Inline class. For example, a Span (an Inline-derived class) can 
only have Inline child elements, but a Figure (also an Inline-derived class) can only have Block child elements. 
Therefore, a diagram is useful for quickly determining what element can be contained in another. As an example, 
let's use the diagram to determine how to construct the flow content of a RichTextBox. 


1. A RichTextBox must contain a FlowDocument which in turn must contain a Block-derived object. The 
following is the corresponding segment from the preceding diagram. 
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Thus far, this is what the markup might look like. 




















<RichTextBox> 

<FlowDocument> 

<!-- One or more Block-derived object... --> 
</FlowDocument> 

</RichTextBox> 


2. According to the diagram, there are several Block elements to choose from including Paragraph, Section, 
Table, List, and BlockUIContainer (see Block-derived classes in the preceding diagram). Let's say we want a 
Table. According to the preceding diagram, a Table contains a TableRowGroup containing TableRow 
elements, which contain TableCell elements which contain a Block-derived object. The following is the 
corresponding segment for Table taken from the preceding diagram. 

Table ►TableRowGroup —►TableRow —►TableCell 

Block-derived Classes O 


The following is the corresponding markup. 

<RichTextBox> 

<FlowDocument> 

<Table> 

<TableRowGroup> 

<TableRow> 

<TableCell> 

<!-- One or more Block-derived object... --> 
</TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 

</RichTextBox> 


3. Again, one or more Block elements are required underneath a TableCell. To make it simple, let's place some 
text inside the cell. We can do this using a Paragraph with a Run element. The following is the corresponding 
segments from the diagram showing that a Paragraph can take an Inline element and that a Run (an Inline 
element) can only take plain text. 
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The following is the entire example in markup. 











<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<RichTextBox> 

<FlowDocument> 

<!-- Normally a table would have multiple rows and multiple 
cells but this code is for demonstration purposes.--> 

<Table> 

<TableRowGroup> 

<TableRow> 

<TableCell> 

<Paragraph> 

<!-- The schema does not actually require 

explicit use of the Run tag in markup. It 
is only included here for clarity. --> 
<Run>Paragraph in a Table Cell.</Run> 

</Paragraph> 

</TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 

</RichTextBox> 

</Page> 


Working with TextElement Content Programmatically 

The contents of a TextElement is made up by collections and so programmatically manipulating the contents of 
TextElement objects is done by working with these collections. There are three different collections used by 
TextElement -derived classes: 

• InlineCollection: Represents a collection of Inline elements. InlineCollection defines the allowable child 
content of the Paragraph, Span, and TextBlock elements. 

• BlockCollection: Represents a collection of Block elements. BlockCollection defines the allowable child 
content of the FlowDocument, Section, Listitem, TableCell, Floater, and Figure elements. 

• ListItemCollection: A flow content element that represents a particular content item in an ordered or 
unordered List. 

You can manipulate (add or remove items) from these collections using the respective properties of Inlines, 
Blocks, and Listitems. The following examples show how to manipulate the contents of a Span using the Inlines 
property. 


NOTE 

Table uses several collections to manipulate its contents, but they are not covered here. For more information, see Table 
Overview. 


The following example creates a new Span object, and then uses the Add method to add two text runs as content 
children of the Span. 

Span spanx = new Span(); 

spanx.Inlines.Add(new Run("A bit of text content..."))j 
spanx.Inlines.Add(new Run("A bit more text content...")); 






Dim spanx As New Span() 

spanx.Inlines.Add(New Run("A bit of text content...")) 
spanx.Inlines.Add(New Run("A bit more text content...")) 


The following example creates a new Run element and inserts it at the beginning of the Span. 
Run runx = new Run("Text to insert..."); 

spanx.Inlines.InsertBefore(spanx.Inlines.FirstInlinej runx); 


Dim runx As New Run("Text to insert...") 

spanx.Inlines.InsertBefore(spanx.Inlines.FirstInlinej runx) 


The following example deletes the last Inline element in the Span. 


spanx.Inlines.Remove(spanx.Inlines.LastInline); 


spanx.Inlines.Remove(spanx.Inlines.LastInline) 


The following example clears all of the contents (Inline elements) from the Span. 


spanx.Inlines.Clear(); 


spanx.Inlines.Clear() 


Types That Share This Content Model 

The following types inherit from the TextElement class and may be used to display the content described in this 
overview. 

Bold, Figure, Floater, Hyperlink, InlineUIContainer, Italic, LineBreak, List, Listitem, Paragraph, Run, Section, Span, 
Table, Underline. 

Note that this list only includes nonabstract types distributed with the Windows SDK. You may use other types that 
inherit from TextElement. 

Types That Can Contain TextElement Objects 

See WPF Content Model. 

See also 

• Manipulate a FlowDocument through the Blocks Property 

• Manipulate Flow Content Elements through the Blocks Property 

• Manipulate a FlowDocument through the Blocks Property 

• Manipulate a Table's Columns through the Columns Property 

• Manipulate a Table's Row Groups through the RowGroups Property 






Table Overview 

3/12/2020 • 10 minutes to read ^ Edit Online 


Table is a block level element that supports grid-based presentation of Flow document content. The flexibility of 
this element makes it very useful, but also makes it more complicated to understand and use correctly. 

This topic contains the following sections. 

• Table Basics 

• How is Table Different then Grid? 

• Basic Table Structure 

• Table Containment 

• Row Groupings 

• Background Rendering Precedence 

• Spanning Rows or Columns 

• Building a Table With Code 

• [Related Topics] 

Table Basics 

How is Table Different then Grid? 

Table and Grid share some common functionality, but each is best suited for different scenarios. A Table is 
designed for use within flow content (see Flow Document Overview for more information on flow content). Grids 
are best used inside of forms (basically anywhere outside of flow content). Within a FlowDocument, Table 
supports flow content behaviors like pagination, column reflow, and content selection while a Grid does not. A 
Grid on the other hand is best used outside of a FlowDocument for many reasons including Grid adds elements 
based on a row and column index, Table does not. The Grid element allows layering of child content, allowing 
more than one element to exist within a single "cell." Table does not support layering. Child elements of a Grid can 
be absolutely positioned relative to the area of their "cell" boundaries. Table does not support this feature. Finally, 
a Grid requires less resources then a Table so consider using a Grid to improve performance. 

Basic Table Structure 

Table provides a grid-based presentation consisting of columns (represented by TableColumn elements) and rows 
(represented by TableRow elements). TableColumn elements do not host content; they simply define columns and 
characteristics of columns. TableRow elements must be hosted in a TableRowGroup element, which defines a 
grouping of rows for the table. TableCell elements, which contain the actual content to be presented by the table, 
must be hosted in a TableRow element. TableCell may only contain elements that derive from Block. Valid child 
elements for a TableCell include. 

• BlockUIContainer 

• List 

• Paragraph 


• Section 




• Table 


NOTE 

TableCell elements may not directly host text content. For more information about the containment rules for flow content 
elements like TableCell, see Flow Document Overview. 


NOTE 

Table is similar to the Grid element but has more capabilities and, therefore, requires greater resource overhead. 


The following example defines a simple 2x3 table with XAML. 




<!-- 

Table is a Block element, and as such must be hosted in a container 
for Block elements. FlowDocument provides such a container. 

--> 

<FlowDocument> 

<Table> 

<!-- 

This table has 3 columns, each described by a TableColumn 
element nested in a Table.Columns collection element. 

--> 

<Table.Columns> 

<TableColumn /> 

<TableColumn /> 

<TableColumn /> 

</Table.Columns> 

<!-- 

This table includes a single TableRowGroup which hosts 2 rows, 
each described by a TableRow element. 

--> 

<TableRowGroup> 

<!-- 

Each of the 2 TableRow elements hosts 3 cells, described by 
TableCell elements. 

--> 

<TableRow> 

<TableCell> 


<!- 


TableCell elements may only host elements derived from Block. 

In this example, Paragaph elements serve as the ultimate content 
containers for the cells in this table. 

> 

Column 1</Paragraph> 


<Paragraph>Cell at Row 
</TableCell> 

<TableCell> 

<Paragraph>Cell at Row 
</TableCell> 

<TableCell> 

<Paragraph>Cell at Row 
</TableCell> 

</TableRow> 

<TableRow> 

<TableCell> 

<Paragraph>Cell at Row 
</TableCell> 

<TableCell> 

<Paragraph>Cell at Row 
</TableCell> 

<TableCell> 

<Paragraph>Cell at Row 
</TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 


1 Column 2</Paragraph> 


1 Column 3</Paragraph> 


2 Column 1</Paragraph> 


2 Column 2</Paragraph> 


2 Column 3</Paragraph> 


The following figure shows how this example renders. 
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Table Containment 

Table derives from the Block element, and adheres to the common rules for Block level elements. A Table element 
may be contained by any of the following elements: 











• FlowDocument 


• TableCell 

• ListBoxItem 

• ListViewItem 

• Section 

• Floater 

• Figure 

Row Groupings 

The TableRowGroup element provides a way to arbitrarily group rows within a table; every row in a table must 
belong to a row grouping. Rows within a row group often share a common intent, and may be styled as a group. 
A common use for row groupings is to separate special-purpose rows, such as a title, header, and footer rows, 
from the primary content contained by the table. 

The following example uses XAML to define a table with styled header and footer rows. 


<Table> 

<Table.Resources> 

<!-- Style for header/footen nows. --> 

<Style x:Key="headenFootenRowStyle" TargetType="{x:Type TableRowGroup}"> 
<Setter Property="FontWeight" \/alue="DemiBold"/> 

<Setter Property="FontSize" \/alue="16"/> 

<Setter Pnopenty="Bacl<gnound" \/alue="LightGray"/> 

</Style> 

<!-- Style for data rows. --> 

<Style x:Key="dataRowStyle" TargetType="{x:Type TableRowGroup}"> 

<Setter Pnopenty="FontSize" \/alue="12"/> 

<Setter Property="FontStyle" Value="Italic"/> 

</Style> 

</Table.Resounces> 

<Table.Columns) 

<TableColumn/> <TableColumn/> <TableColumn/> <TableColumn/> 

</Table.Columns) 

<!-- This TableRowGnoup hosts a header row for the table. --) 
<TableRowGroup Style="{StaticResource headerFooterRowStyle}") 

<TableRow) 

<TableCell/) 

<TableCell)<Paragraph)Gizmos</Paragraphx/TableCell) 

<TableCell)<Paragraph)Thingamajigs</Paragraph)</TableCell) 

<TableCell)<Paragraph)Doohickies</Paragraph)</TableCell) 

</TableRow) 

</TableRowGnoup) 

<!-- This TableRowGnoup hosts the main data rows for the table. --) 
<TableRowGroup Style="{StaticResource dataRowStyle}") 

<TableRow) 

<TableCell)<Paragraph Foreground="Blue")Blue</Paragraph)</TableCell) 
<TableCell)<Paragraph)l</Paragraph)</TableCell) 
<TableCell)<Paragraph)2</Paragraph)</TableCell) 
<TableCell)<Paragraph)3</Paragraph) </TableCell) 

</TableRow) 

<TableRow) 

<TableCell)<Paragraph Foreground="Red")Red</Paragraph)</TableCell) 
<TableCell)<Paragraph)l</Paragraph)</TableCell) 
<TableCell)<Paragraph)2</Paragraph)</TableCell) 
<TableCell)<Paragraph)3</Paragraph)</TableCell) 

</TableRow) 

<TableRow) 

<TableCell)<Paragraph Foreground="Green")Green</Paragraph)</TableCell) 
<TableCell)<Paragraph)l</Paragraph)</TableCell) 
<TableCell)<Paragraph)2</Paragraph)</TableCell) 
<TableCell)<Paragraph)3</Paragraph)</TableCell) 

</TableRow) 

</TableRowGnoup) 

<!-- This TableRowGnoup hosts a footer row for the table. --) 
<TableRowGroup Style="{StaticResource headerFooterRowStyle}") 

<TableRow) 

<TableCell)<Paragraph)Totals</Paragraph)</TableCell) 

<TableCell)<Paragraph)3</Paragraph)</TableCell) 

<TableCell)<Paragraph)6</Paragraph)</TableCell) 

<TableCell) 

<Table)</Table) 

</TableCell) 

</TableRow) 

</TableRowGnoup) 

</Table) 


The following figure shows how this example renders. 
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Background Rendering Precedence 

Table elements render in the following order (z-order from lowest to highest). This order cannot be changed. For 
example, there is no "Z-order" property for these elements that you can use to override this established order. 

1. Table 

2. TableColumn 

3. TableRowGroup 

4. TableRow 

5. TableCell 

Consider the following example, which defines background colors for each of these elements within a table. 

<Table Background="Yellow"> 

<Table.Columns> 

<TableColumn/> 

<TableColumn Background="LightGreen"/> 

<TableColumn/> 

</Table.Columns> 

<TableRowGroup> 

<TableRow> 

<TableCell/><TableCell/><TableCell/> 

</TableRow> 

</TableRowGr'oup> 

<TableRowGroup Background="Tan"> 

<TableRow> 

<TableCell/><TableCell/><TableCell/> 

</TableRow> 

<TableRow Background="LightBlue"> 

<TableCell/><TableCell Background="Purple"/><TableCell/> 

</TableRow> 

<TableRow> 

<TableCell/><TableCell/><TableCell/> 

</TableRow> 

</TableRowGroup> 

<TableRowGroup> 

<TableRow> 

<TableCell/><TableCell/><TableCell/> 

</TableRow> 

</TableRowGroup> 

</Table> 


The following figure shows how this example renders (showing background colors only). 


Spanning Rows or Columns 

Table cells may be configured to span multiple rows or columns by using the RowSpan or ColumnSpan attributes, 
respectively. 








Consider the following example, in which a cell spans three columns. 


<Table> 

<Table.Columns> 

<TableColumn/> 

<TableColumn/> 

<TableColumn/> 

</Table.Columns> 

<TableRowGroup> 

<TableRow> 

<TableCell ColumnSpan="3" Backgnound="Cyan"> 

<Panagraph>This cell spans all three columns.</Paragraph> 

</TableCell> 

</TableRow> 

<TableRow> 

<TableCell Background="LightGray"><Paragraph>Cell l</Paragraph></TableCell> 
<TableCell Background="LightGray"><Paragraph>Cell 2</Paragraph></TableCell> 
<TableCell Background="LightGray"><Paragraph>Cell 3</Paragraph></TableCell> 
</TableRow> 

</TableRowGroup> 

</Table> 


The following figure shows how this example renders. 


This cell spans all three columns. 

Cell 1 Cell 2 Cell 3 


Building a Table With Code 

The following examples show how to programmatically create a Table and populate it with content. The contents 
of the table are apportioned into five rows (represented by TableRow objects contained in a RowGroups object) 
and six columns (represented by TableColumn objects). The rows are used for different presentation purposes, 
including a title row intended to title the entire table, a header row to describe the columns of data in the table, 
and a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not 
inherent to the table; these are simply rows with different characteristics. Table cells contain the actual content, 
which can be comprised of text, images, or nearly any other user interface (Ul) element. 

First, a FlowDocument is created to host the Table, and a new Table is created and added to the contents of the 
FlowDocument. 


// Create the parent FlowDocument... 
flowDoc = new FlowDocument(); 

// Create the Table... 
table! = new Table(); 

// ...and add it to the FlowDocument Blocks collection. 
flowDoc. Blocks. Add (table!); 

// Set some global formatting properties for the table. 

table!.Cellspacing = !0; 

table!.Background = Brushes.White; 






' Create the parent FlowDocument... 
flowDoc = New FlowDocument() 

' Create the Table... 
tablel = New Table() 

' ...and add it to the FlowDocument Blocks collection. 
flowDoc.Blocks.Add(tablel) 

' Set some global formatting properties for the table. 

tablel.Cellspacing = 10 

tablel.Background = Brushes.White 


Next, six TableColumn objects are created and added to the table's Columns collection, with some formatting 
applied. 



// Create 6 columns and add them to the table's Columns collection. 

int numberOfColumns = 6; 

for (int X = 0; X < numberOfColumns; x++) 

{ 

tablel.Columns.Add(new TableColumn()); 

// Set alternating background colors for the middle colums. 
if(x%2 == 0) 

tablel.Columns[x].Background = Brushes.Beige; 

else 

tablel.Columns[x].Background = Brushes.LightSteelBlue; 

} 


' Create 6 columns and add them to the table's Columns collection. 
Dim numberOfColumns = 6 
Dim X 

For X = 0 To numberOfColumns 

tablel.Columns.Add(new TableColumn()) 

' Set alternating background colors for the middle colums. 

If X Mod 2=0 Then 

tablel.Columns(x).Background = Brushes.Beige 

Else 

tablel.Columns(x).Background = Brushes.LightSteelBlue 
End If 
Next X 


Next, a title row is created and added to the table with some formatting applied. The title row happens to contain 
a single cell that spans all six columns in the table. 





// Create and add an empty TableRowGroup to hold the table's Rows, 
table!.RowGroups.Add(new TableRowGroup()); 

// Add the first (title) row. 

table!.RowGroups[0].Rows.Add(new TableRow())j 

// Alias the current working row for easy reference. 

TableRow currentRow = table!.RowGroups[0].Rows[0]; 

// Global formatting for the title row. 
currentRow.Background = Brushes.Silver; 
currentRow.FontSize = 40; 

currentRow.FontWeight = System.Windows.FontWeights.Bold; 

// Add the header row with content^ 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("2004 Sales Project")))); 
// and set the row to span all 6 columns. 
currentRow.Cells[0].ColumnSpan = 6; 


' Create and add an empty TableRowGroup to hold the table's Rows, 
table!.RowGroups.Add(new TableRowGroup()) 

' Add the first (title) row. 

table!.RowGroups(0).Rows.Add(new TableRow()) 

' Alias the current working row for easy reference. 

Dim currentRow As New TableRow() 
currentRow = table!.RowGroups(0).Rows(0) 

' Global formatting for the title row. 
currentRow.Background = Brushes.Silver 
currentRow.FontSize = 40 

currentRow.FontWeight = System.Windows.FontWeights.Bold 
' Add the header row with content^ 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("2004 Sales Project")))) 
' and set the row to span all 6 columns. 
currentRow.Cells(0).ColumnSpan = 6 


Next, a header row is created and added to the table, and the cells in the header row are created and populated 
with content. 


// Add the second (header) row. 

table!.RowGroups[0].Rows.Add(new TableRow()); 

currentRow = table!.RowGroups[0].Rows[!]; 

// Global formatting for the header row. 

currentRow.FontSize = !8; 

currentRow.FontWeight = FontWeights.Bold; 


// Add cells with content to the second row. 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 


Run("Product")))); 
Run("Quarter !")))); 
Run("Quarter 2")))); 
Run("Quarter 3")))); 
Run("Quarter 4")))); 
RunC'TOTAL")))); 




' Add the second (header) row. 
tablel.RowGroups(0).Rows.Add(new TableRow()) 
currentRow = tablet.RowGroups(0).Rows(l) 


' Global formatting for the header row. 

currentRow.FontSize = 18 

currentRow.FontWeight = FontWeights.Bold 


' Add cells with content to the second row. 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 


Run("Product")))) 
Run("Quarter 1")))) 
Run("Quarter 2")))) 
Run("Quarter 3")))) 
Run("Quarter 4")))) 
RunC'TOTAL")))) 


Next, a row for data is created and added to the table, and the cells in this row are created and populated with 
content. Building this row is similar to building the header row, with slightly different formatting applied. 


// Add the third row. 

tablel.RowGroups[0].Rows.Add(new TableRow())j 
currentRow = tablet.RowGroups[0].Rows[2]; 


// Global formatting for the row. 

currentRow.FontSize = 12; 

currentRow.FontWeight = FontWeights.Normal; 


// Add cells with content to the third row. 

currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 

Run("Widgets")))); 

Run("$50,000")))); 

Run("$55,000")))); 

Run("$60,000")))); 

Run("$65,000")))); 

Run("$230,000")))); 

// Bold the first cell. 

currentRow.Cells[0].FontWeight = FontWeights.Bold; 



' Add the third row. 

tablel.RowGroups(0).Rows.Add(new TableRow()) 
currentRow = tablel.RowGroups(0).Rows(2) 


' Global formatting for the row. 

currentRow.FontSize = 12 

currentRow.FontWeight = FontWeights.Normal 


' Add cells with content to the third row. 

currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 

Run("Widgets")))) 

Run("$50,000")))) 

Run("$55,000")))) 

Run("$60,000")))) 

Run("$65,000")))) 

Run("$230,000")))) 

' Bold the first cell. 

currentRow.Cells(0).FontWeight = FontWeights.Bold 



Finally, a footer row is created, added, and formatted. Like the title row, the footer contains a single cell that spans 
all six columns in the table. 





tablel.RowGroups[0].Rows.Add(new TableRow())j 
currentRow = tablel.RowGroups[0].Rows[3]; 

// Global formatting for the footer row. 
currentRow.Background = Brushes.LightGray; 
currentRow.FontSize = 18; 

currentRow.FontWeight = System.Windows.FontWeights.Normal; 

// Add the header row with content^ 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("Projected 2004 Revenue: $810^000")))); 
// and set the row to span all 6 columns. 
currentRow.Cells[0].ColumnSpan = 6; 


tablet.RowGroups(0).Rows.Add(new TableRow()) 
currentRow = tablet.RowGroups(0).Rows(3) 

' Global formatting for the footer row. 
currentRow.Background = Brushes.LightGray 
currentRow.FontSize = 18 

currentRow.FontWeight = System.Windows.FontWeights.Normal 
' Add the header row with contentj 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("Projected 2004 Revenue: $810^000")))) 
' and set the row to span all 6 columns. 
currentRow.Cells(0).ColumnSpan = 6 


See also 

• Flow Document Overview 

• Define a Table with XAML 

• Documents in WPF 

• Use Flow Content Elements 
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The topics in this section describe how to accomplish common tasks using various flow content elements and 
related features. 

In This Section 

Adjust Spacing Between Paragraphs 
Build a Table Programmatically 

Change the FlowDirection of Content Programmatically 
Change the Textwrapping Property Programmatically 
Define a Table with XAML 
Alter the Typography of Text 
Enable Text Trimming 

Insert an Element Into Text Programmatically 

Manipulate Flow Content Elements through the Blocks Property 

Manipulate Flow Content Elements through the Inlines Property 

Manipulate a FlowDocument through the Blocks Property 

Manipulate a Table's Columns through the Columns Property 

Manipulate a Table's Row Groups through the RowGroups Property 

Use Flow Content Elements 

Use FlowDocument Column-Separating Attributes 

Reference 

FlowDocument 

Block 

Inline 

Related Sections 


Documents in WPF 
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This example shows how to adjust or eliminate spacing between paragraphs in flow content 

In flow content extra space that appears between paragraphs is the result of margins set on these paragraphs; 
thus, the spacing between paragraphs can be controlled by adjusting the margins on those paragraphs. To 
eliminate extra spacing between two paragraphs altogether, set the margins for the paragraphs to 0. To achieve 
uniform spacing between paragraphs throughout an entire FlowDocument, use styling to set a uniform margin 
value for all paragraphs in the FlowDocument. 

It is important to note that the margins for two adjacent paragraphs will "collapse" to the larger of the two margins, 
rather than doubling up. So, if two adjacent paragraphs have margins of 20 pixels and 40 pixels respectively, the 
resulting space between the paragraphs is 40 pixels, the larger of the two margin values. 

Example 

The following example uses styling to set the margin for all Paragraph elements in a FlowDocument to 0, which 
effectively eliminates extra spacing between paragraphs in the FlowDocument. 

<FlowDocument> 

<FlowDocument.Resounces> 

<!-- This style is used to set the margins for all paragraphs in the FlowDocument to 0. --> 

<Style TargetType="{x:Type Paragraph}"> 

<Setter Property="Margin" Value="0"/> 

</Style> 

</FlowDocument.Resources> 

<Paragraph> 

Spacing between paragraphs is caused by margins set on the paragraphs. Two adjacent margins 
will "collapse" to the larger of the two margin widths^ rather than doubling up. 

</Paragraph> 

<Paragraph> 

To eliminate extra spacing between two paragraphs, just set the paragraph margins to 0. 

</Paragraph> 

</FlowDocument> 
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The following examples show how to programmatically create a Table and populate it with content. The contents of 
the table are apportioned into five rows (represented by TableRow objects contained in a RowGroups object) and 
six columns (represented by TableColumn objects). The rows are used for different presentation purposes, 
including a title row intended to title the entire table, a header row to describe the columns of data in the table, and 
a footer row with summary information. Note that the notion of "title", "header", and "footer" rows are not inherent 
to the table; these are simply rows with different characteristics. Table cells contain the actual content, which can be 
comprised of text, images, or nearly any other user interface (Ul) element. 

Example 

First, a FlowDocument is created to host the Table, and a new Table is created and added to the contents of the 
FlowDocument. 


// Create the parent FlowDocument... 
flowDoc = new FlowDocument(); 

// Create the Table... 
table! = new Table(); 

// ...and add it to the FlowDocument Blocks collection, 
flowDoc.Blocks.Add(table!); 

// Set some global formatting properties for the table. 

table!.Cellspacing = !0; 

table!.Background = Brushes.White; 


' Create the parent FlowDocument... 
flowDoc = New FlowDocument() 

' Create the Table... 
table! = New Table() 

' ...and add it to the FlowDocument Blocks collection. 
flowDoc.Blocks.Add(table!) 

' Set some global formatting properties for the table. 

table!.Cellspacing = !0 

table!.Background = Brushes.White 


Example 

Next, six TableColumn objects are created and added to the table's Columns collection, with some formatting 
applied. 


NOTE 

Note that the table's Columns collection uses standard zero-based indexing. 






// Create 6 columns and add them to the table's Columns collection. 

int numberOfColumns = 6; 

for (int X = 0; X < numberOfColumns; x++) 

{ 

table!.Columns.Add(new TableColumn()); 

// Set alternating background colors for the middle colums. 
if(x%2 == 0) 

table!.Columns[x].Background = Brushes.Beige; 

else 

table!.Columns[x].Background = Brushes.LightSteelBlue; 


' Create 6 columns and add them to the table's Columns collection. 
Dim numberOfColumns = 6 
Dim X 

For X = 0 To numberOfColumns 

table!.Columns.Add(new TableColumn()) 

' Set alternating background colors for the middle colums. 

If X Mod 2 = 0 Then 

table!.Columns(x).Background = Brushes.Beige 

Else 

table!.Columns(x).Background = Brushes.LightSteelBlue 
End If 
Mext X 


Example 

Next, a title row is created and added to the table with some formatting applied. The title row happens to contain a 
single cell that spans all six columns in the table. 

// Create and add an empty TableRowGroup to hold the table's Rows, 
table!.RowGroups.Add(new TableRowGroup()); 

// Add the first (title) row. 

table!.RowGroups[0].Rows.Add(new TableRow()); 

// Alias the current working row for easy reference. 

TableRow currentRow = table!.RowGroups[0].Rows[0]; 

// Global formatting for the title row. 
currentRow.Background = Brushes.Silver; 
currentRow.FontSize = 40; 

currentRow.FontWeight = System.Windows.FontWeights.Bold; 

// Add the header row with contentj 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("2004 Sales Project")))); 

// and set the row to span all 6 columns. 
currentRow.Cells[0].ColumnSpan = 6; 




' Create and add an empty TableRowGroup to hold the table's Rows, 
tablet.RowGroups.Add(new TableRowGroup()) 

' Add the first (title) row. 

tablet.RowGroups(0).Rows.Add(new TableRow()) 

' Alias the current working row for easy reference. 

Dim currentRow As New TableRow() 
currentRow = tablet.RowGroups(0).Rows(0) 

' Global formatting for the title row. 
currentRow.Background = Brushes.Silver 
currentRow.FontSize = 40 

currentRow.FontWeight = System.Windows.FontWeights.Bold 
' Add the header row with content^ 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("2004 Sales Project")))) 
' and set the row to span all 6 columns. 
currentRow.Cells(0).ColumnSpan = 6 


Example 

Next, a header row is created and added to the table, and the cells in the header row are created and populated 
with content. 


// Add the second (header) row. 

tablet.RowGroups[0].Rows.Add(new TableRow()); 

currentRow = tablel.RowGroups[0].Rows[l]; 

// Global formatting for the header row. 

currentRow.FontSize = 18; 

currentRow.FontWeight = FontWeights.Bold; 


// Add cells with content to the second row. 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 


Run("Product")))); 
Run("Quarter 1")))); 
Run("Quarter 2")))); 
Run("Quarter 3")))); 
Run("Quarter 4")))); 
RunC'TOTAL")))); 


' Add the second (header) row. 

tablet.RowGroups(0).Rows.Add(new TableRow()) 

currentRow = tablet.RowGroups(0).Rows(l) 

' Global formatting for the header row. 

currentRow.FontSize = 18 

currentRow.FontWeight = FontWeights.Bold 


' Add cells with content to the second row. 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 


Run("Product")))) 
Run("Quarter 1")))) 
Run("Quarter 2")))) 
Run("Quarter 3")))) 
Run("Quarter 4")))) 
RunC'TOTAL")))) 


Example 


Next, a row for data is created and added to the table, and the cells in this row are created and populated with 




content. Building this row is similar to building the header row, with slightly different formatting applied. 


// Add the third row. 

tablet.RowGroups[0].Rows.Add(new TableRow()); 
currentRow = tablet.RowGroups[0].Rows[2]; 

// Global formatting for the row. 

currentRow.FontSize = 12; 

currentRow.FontWeight = FontWeights.Normal; 


// Add cells with content to the third 
currentRow.Cells.Add(new TableCell(new 
currentRow.Cells.Add(new TableCell(new 
currentRow.Cells.Add(new TableCell(new 
currentRow.Cells.Add(new TableCell(new 
currentRow.Cells.Add(new TableCell(new 
currentRow.Cells.Add(new TableCell(new 


row. 

Paragraph(new 

Paragraph(new 

Paragraph(new 

Paragraph(new 

Paragraph(new 

Paragraph(new 


Run("Widgets")))); 
Run("$50,000")))); 
Run("$55,000")))); 
Run("$60,000")))); 
Run("$65,000")))); 
Run("$230,000")))); 


// Bold the first cell. 

currentRow.Cells[0].FontWeight = FontWeights.Bold; 


' Add the third row. 

tablet.RowGroups(0).Rows.Add(new TableRow()) 
currentRow = tablet.RowGroups(0).Rows(2) 


' Global formatting for the row. 

currentRow.FontSize = 12 

currentRow.FontWeight = FontWeights.Normal 


Add cells with content to the third row. 


currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 
currentRow.Cells.Add(new TableCell(new Paragraph(new 


Run("Widgets")))) 

Run("$50,000")))) 

Run("$55,000")))) 

Run("$60,000")))) 

Run("$65,000")))) 

Run("$230,000")))) 


' Bold the first cell. 

currentRow.Cells(0).FontWeight = FontWeights.Bold 


Example 

Finally, a footer row is created, added, and formatted. Like the title row, the footer contains a single cell that spans 
all six columns in the table. 


tablet.RowGroups[0].Rows.Add(new TableRow()); 
currentRow = tablet.RowGroups[0].Rows[3]; 

// Global formatting for the footer row. 
currentRow.Background = Brushes.LightGray; 
currentRow.FontSize = 18; 

currentRow.FontWeight = System.Windows.FontWeights.Normal; 

// Add the header row with content^ 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("Projected 2004 Revenue: $810,000")))); 
// and set the row to span all 6 columns. 
currentRow.Cells[0].ColumnSpan = 6; 







tablel.RowGroups(0).Rows.Add(new TableRow()) 
currentRow = tablel.RowGnoups(0).Rows(3) 

' Global formatting for the footer row. 
currentRow.Background = Brushes.LightGray 
currentRow.FontSize = 18 

currentRow.FontWeight = System.Windows.FontWeights.Normal 
' Add the header row with content, 

currentRow.Cells.Add(new TableCell(new Paragraph(new Run("Projected 2004 Revenue: $810,000")))) 
' and set the row to span all 6 columns. 
currentRow.Cells(0).ColumnSpan = 6 


See also 

• Table Overview 



How to: Change the FlowDirection of Content 
Programmatically 

3/5/2019 • 2 minutes to read i Edit Online 


This example shows how to programmatically change the FlowDirection property of a FlowDocumentReader. 

Example 

Two Button elements are created, each representing one of the possible values of FlowDirection. When a button is 
clicked, the associated property value is applied to the contents of a FlowDocumentReader named tfi . The 
property value is also written to a TextBlock named txti . 

<Stacl<Panel Docl<Panel.Docl<="Top" Orientation="Horizontal" Margin="0,0,0,10"> 

<Button Click="LR">LeftToRight</Button> 

<Button Click="RL">RightToLeft</Button> 

</StackPanel> 

<TextBlock Name="txtl" DockPanel.Dock="Bottom" Margin="0j50,0,0"/> 

<FlowDocumentReader> 

<FlowDocument FontFamily="Arial" IMame="tfl"> 

<Panagraph> 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj 
sed diam nonummy nibh euismod tincidunt ut laoreet dolors 
magna aliquam erat volutpat. Ut wisi enim ad minim veniam^ 
quis nostrud exerci tation ullamcorper suscipit lobortis nisi 
ut aliquip ex ea commodo consequat. Duis autem vel sum iriure. 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj sed 
diam nonummy nibh euismod tincidunt ut laoreet dolors magna 
aliquam erat volutpat. Ut wisi enim ad minim veniam^ quis 
nostrud exerci tation ullamcorper suscipit lobortis nisi ut 
uliquip ex ea commodo consequat. Duis autem vel eum iriure. 

Lorem ipsum dolor sit amet^ consectetuer adipiscing elitj sed 
diam nonummy nibh euismod tincidunt ut laoreet dolors magna 
aliquam erat volutpat. Ut wisi enim ad minim veniam^ quis 
nostrud exerci tation ullamcorper suscipit lobortis nisi ut 
aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

</Paragraph> 

<Paragraph> 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj sed 
diam nonummy nibh euismod tincidunt ut laoreet dolors magna 
aliquam erat volutpat. Ut wisi enim ad minim veniam^ quis 
nostrud exerci tation ullamcorper suscipit lobortis nisi ut 
aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj sed 
diam nonummy nibh euismod tincidunt ut laoreet dolors magna 
aliquam erat volutpat. Ut wisi enim ad minim veniam^ quis 
nostrud exerci tation ullamcorper suscipit lobortis nisi ut 
aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj sed 
diam nonummy nibh euismod tincidunt ut laoreet dolors magna 
aliquam erat volutpat. Ut wisi enim ad minim veniam^ quis 
nostrud exerci tation ullamcorper suscipit lobortis nisi ut 
aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

</Paragraph> 

</FlowDocument> 

</FlowDocumentReader> 







Example 

The events associated with the button clicks defined above are handled in a C# code-behind file. 


private void LR(object senderj RoutedEventArgs e) 

{ 

tfl.FlowDirection = FlowDirection.LeftToRight; 
txtl.Text = "FlowDirection is now " + tfl.FlowDirection; 

} 

private void RL(object sender^ RoutedEventArgs e) 

{ 

tfl.FlowDirection = FlowDirection.RightToLeft; 
txtl.Text = "FlowDirection is now " + tfl.FlowDirection; 

} 


Private Sub LR(ByVal sender As Object^ ByVal e As RoutedEventArgs) 
tfl.FlowDirection = FlowDirection.LeftToRight 
txtl.Text = "FlowDirection is now " & tfl.FlowDirection 
End Sub 

Private Sub RL(ByVal sender As Objectj ByVal e As RoutedEventArgs) 
tfl.FlowDirection = FlowDirection.RightToLeft 
txtl.Text = "FlowDirection is now " & tfl.FlowDirection 
End Sub 



How to: Change the TextWrapping Property 
Programmatically 

4/8/2019 • 2 minutes to read i Edit Online 


Example 

The following code example shows how to change the value of the TextWrapping property programmatically. 

Three Button elements are placed within a StackPanel element in XAML. Each Click event for a Button corresponds 
with an event handler in the code. The event handlers use the same name as the TextWrapping value they will apply 
to txt 2 when the button is clicked. Also, the text in txti (a TextBlock not shown in the XAML) is updated to reflect 
the change in the property. 

<Stacl<Panel Or'ientation="Hor'izontal" Mar'gin="0j0j0j20"> 

<Button Name="btnl" Bacl<gr'ound="Silver'" Width="100" Click="Wrap">Wrap</Button> 

<Button Name="btn2" Bacl<gr'ound="Silver'" Width="100" Click="NoWrap">NoWrap</Button> 

<Button Name="btn4" Backgr'ound="Silver'" Width="100" Click="WrapWithOverflow">WrapWithOverflow</Button> 
</StackPanel> 

<TextBlock Nanie="txt2" TextWrapping="Wrap" Margin="0j0j0j20" Foreground="Black"> 

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Lorem ipsum dolor sit ametj 
consectetuer adipiscing elit.Lorem ipsum dolor sit aetj consectetuer adipiscing elit. 

Lorem ipsum dolor sit amet^ consectetuer adipiscing elit. 

</TextBlock> 


private void Wrap(object sender^ RoutedEventArgs e) 

{ 

txt2.Textwrapping = System.Windows.TextWrapping.Wrap; 
txtl.Text = "The TextWrap property is currently set to Wrap."; 

} 

private void NoWrap(object sender^ RoutedEventArgs e) 

{ 

txt2.Textwrapping = System.Windows.TextWrapping.NoWrap; 
txtl.Text = "The TextWrap property is currently set to NoWrap."; 

} 

private void WrapWithOverflow(object sender, RoutedEventArgs e) 

{ 

txt2.Textwrapping = System.Windows.TextWrapping.WrapWithOverflow; 
txtl.Text = "The TextWrap property is currently set to WrapWithOverflow."; 

} 






Private Sub Wrap(ByVal sender As Object^ ByVal e As System.Windows.RoutedEventArgs) 
txt2.Textwrapping = System.Windows.Textwrapping.Wrap 
txtl.Text = "The TextWrap property is currently set to Wrap." 

End Sub 

Private Sub NoWrap(ByVal sender As Objectj ByVal e As System.Windows.RoutedEventArgs) 
txt2.Textwrapping = System.Windows.Textwrapping.NoWrap 
txtl.Text = "The TextWrap property is currently set to NoWrap." 

End Sub 

Private Sub WrapWithOverflow(ByVal sender As Object, ByVal e As System.Windows.RoutedEventArgs) 
txt2.Textwrapping = System.Windows.Textwrapping.WrapWithOverflow 
txtl.Text = "The TextWrap property is currently set to WrapWithOverflow." 

End Sub 


See also 

• Textwrapping 

• Textwrapping 



How to: Define a Table with XAML 

3/29/2019 • 2 minutes to read ^ Edit Online 


The following example demonstrates how to define a Table using Extensible Application Markup Language (XAML). 
The example table has four columns (represented by TableColumn elements) and several rows (represented by 
TableRow elements) containing data as well as title, header, and footer information. Rows must be contained in a 
TableRowGroup element. Each row in the table is comprised of one or more cells (represented by TableCell 
elements). Content in a table cell must be contained in a Block element; in this case Paragraph elements are used. 
The table also hosts a hyperlink (represented by the Hyperlink element) in the footer row. 

Example 

<FlowDocumentReader'> 

<FlowDocument> 

<Table CellSpacing="5"> 

<Table.Columns> 

<TableColumn/> 

<TableColumn/> 

<TableColumn/> 

<TableColumn/> 

</Table.Columns> 

<TableRowGroup> 

<!-- Title row for the table. --> 

<TableRow Background="SkyBlue"> 

<TableCell ColumnSpan="4" TextAlignment="Center"> 

<Paragraph FontSize="24pt" FontWeight="Bold">Planetary Information</Paragraph> 

</TableCell> 

</TableRow> 

<!-- Header row for the table. --> 

<TableRow Background="LightGoldenrodYellow"> 

<TableCell><Paragraph FontSize="14pt" FontWeight="Bold">Planet</Paragraph></TableCell> 
<TableCell><Paragraph FontSize="14pt" FontWeight="Bold">Mean Distance from Sun</Paragraph> 
</TableCell> 

<TableCell><Paragraph FontSize="14pt" FontWeight="Bold">Mean Diameter</Paragraph></TableCell> 
<TableCell><Paragraph FontSize="14pt" FontWeight="Bold">Approximate Mass</Paragraph></TableCell> 
</TableRow> 

<!-- Sub-title row for the inner planets. --> 

<TableRow> 

<TableCell ColumnSpan="4"><Paragraph FontSize="14pt" FontWeight="Bold">The Inner Planets</Paragraph> 
</TableCell> 

</TableRow> 

<!-- Four data rows for the inner planets. --> 

<TableRow> 

<TableCell><Paragraph>Mercury</Paragraph></TableCell> 

<TableCell><Paragraph>57j910j000 km</Paragraph></TableCell> 

<TableCell><Paragraph>4,880 km</Paragraph></TableCell> 

<TableCell><Paragraph>3.30e23 kg</Paragraph></TableCell> 

</TableRow> 

<TableRow Background="lightgray"> 

<TableCell><Paragraph>Venus</Paragraph></TableCell> 

<TableCell><Paragraph>108j200j000 km</Paragraph></TableCell> 

<TableCell><Paragraph>12j103.6 km</Paragraph></TableCell> 
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</TableRow> 

<TableRow> 

<TableCell><Par'agraph>Ear'th</Paragraph></TableCell> 

<TableCell><Paragraph>149j600j000 km</Paragraph></TableCell> 

<TableCell><Paragraph>12j756.3 km</Paragraph></TableCell> 

<TableCell><Paragraph>5.972e24 kg</Paragraph></TableCell> 

</TableRow> 

<TableRow Background="lightgray"> 

<TableCell><Paragraph>Mars</Paragraph></TableCell> 

<TableCell><Paragraph>227,940,000 km</Paragraph></TableCell> 

<TableCell><Paragraph>6,794 km</Paragraph></TableCell> 

<TableCell><Paragraph>6.4219e23 kg</Paragraph></TableCell> 

</TableRow> 

<!-- Sub-title row for the outter planets. --> 

<TableRow> 

<TableCell ColumnSpan="4"><Paragraph FontSize="14pt" FontWeight="Bold">The Major Outer 
Planets</Paragraph></TableCell> 

</TableRow> 

<!-- Four data rows for the major outter planets. --> 

<TableRow> 

<TableCell><Paragraph>3upiter</Paragraph></TableCell> 

<TableCell><Paragraph>778,330,000 km</Paragraph></TableCell> 

<TableCell><Paragraph>142,984 km</Paragraph></TableCell> 

<TableCell><Paragraph>1.900e27 kg</Paragraph></TableCell> 

</TableRow> 

<TableRow Background="lightgray"> 

<TableCell><Paragraph>Saturn</Paragraph></TableCell> 

<TableCell><Paragraph>1,429,400,000 km</Paragraph></TableCell> 

<TableCell><Paragraph>120,536 km</Paragraph></TableCell> 

<TableCell><Paragraph>5.68e26 kg</Paragraph></TableCell> 

</TableRow> 

<TableRow> 

<TableCell><Paragraph>Uranus</Paragraph></TableCell> 

<TableCell><Paragraph>2,870,990,000 km</Paragraph></TableCell> 

<TableCell><Paragraph>51,118 km</Paragraph></TableCell> 

<TableCell><Paragraph>8.683e25 kg</Paragraph></TableCell> 

</TableRow> 

<TableRow Background="lightgray"> 

<TableCell><Paragraph>Neptune</Paragraph></TableCell> 

<TableCell><Paragraph>4,504,000,000 km</Paragraph></TableCell> 

<TableCell><Paragraph>49,532 km</Paragraph></TableCell> 

<TableCell><Paragraph>1.0247e26 kg</Paragraph></TableCell> 

</TableRow> 

<!-- Footer row for the table. --> 

<TableRow> 

<TableCell ColumnSpan="4"><Paragraph FontSize="10pt" FontStyle="Italic"> 

Information from the 

<Hyperlink NavigateUri="http://encarta.msn.com/encnet/refpages/artcenter.aspx">Fncarta</Hyperlink> 
web site. 

</Paragraph></TableCell> 

</TableRow> 

</TableRowGroup> 

</Table> 

</FlowDocument> 

</FlowDocumentReader> 


The following figure shows how the table defined in this example renders: 




Planetary Information 

Planet 

Mean 

Distance 
from Sun 

Mean 

Diameter 

Approximate 

Mass 

The Inner Planets 



Mercury 

57,910,000 km 

4,880 km 

3.30e23 kg 

Venus 

108,200,000 km 

12,103.6 km 

4.869e24 kg 

Earth 

149,600,000 km 

12,756.3 km 

5.972e24 kg 

Mars 

227,940,000 km 

6,794 km 

6.4219e23 kg 

The Major Outer Planets 



Jupiter 

778,330,000 km 

142,984 km 

1.900e27 kg 

Saturn 

1,429,400,000 km 

120,536 km 

5.68e26 kg 

Uranus 

2,870,990,000 km 

51,118 km 

8.683e25 kg 



How-to: Alter the Typography of Text 

4/8/2019 • 2 minutes to read ^ Edit Online 


The following example shows how to set the Typography attribute, using Paragraph as the example element. 

Example 

<Par'agraph 

TextAlignment="Left" 

FontSize="18" 

FontFamily="Palatino Linotype" 

Typography.NumeralStyle="01dStyle" 

Typography.Fraction="Stacked" 

Typography.Variants="Inferior" 

> 

<Run> 

This text has some altered typography characteristics. Note 
that use of an open type font is necessary for most typographic 
properties to be effective. 

</Run> 

<LineBreak/><LineBreak/> 

<Run> 

0123456789 10 11 12 13 
</Run> 

<LineBreak/><LineBreak/> 

<Run> 

1/2 2/3 3/4 
</Run> 

</Paragraph> 


The following figure shows how this example renders. 


"^his text has some altered t},*pography characteristics- ^ote that use 
of an open t\*pe font is necessary* for most h'pographic properties to 
be effecti\-e. 

012345678910111213 

12 3 

III 


In contrast, the following figure shows how a similar example with default typographic properties renders. 

This text has some altered typography 
characteristics. Note that use of an open tvpe font is 
necessary for most hpographic properties to be 
effective. 

0123456789 10 1112 13 
1/2 2/3 3/4 


Example 


The following example shows how to set the Typography property programmatically. 







Paragraph par = new Paragraph(); 

Run runText = new Run( 

"This text has some altered typography characteristics. Note" + 
"that use of an open type font is necessary for most typographic" + 
"properties to be effective."); 

Run runNumerals = new Run("0123456789 10 11 12 13"); 

Run runfractions = new Run("l/2 2/3 3/4"); 

par.Inlines.Add(runText); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(runNumerals); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(new LineBreak()); 
par.Inlines.Add(runFractions); 

par.TextAlignment = TextAlignment.Left; 
par.FontSize = 18; 

par.FontFamily = new FontFamilyC'Palatino Linotype"); 

par.Typography.NumeralStyle = FontNumeralStyle.OldStyle; 
par.Typography.Fraction = FontFraction.Stacked; 
par.Typography.Variants = FontVariants.Inferior; 


Dim par As New Paragraph() 

Dim runText As New Run("This text has some altered typography characteristics. Note" & "that use of an open 
type font is necessary for most typographic" & "properties to be effective.") 

Dim runNumerals As New Run("0123456789 10 11 12 13") 

Dim runfractions As New Run("l/2 2/3 3/4") 

par.Inlines.Add(runText) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(runNumerals) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(New LineBreak()) 
par.Inlines.Add(runFractions) 

par.TextAlignment = TextAlignment.Left 
par.FontSize = 18 

par.FontFamily = New FontFamilyC'Palatino Linotype") 

par.Typography.NumeralStyle = FontNumeralStyle.OldStyle 
par.Typography.Fraction = FontFraction.Stacked 
par.Typography.Variants = FontVariants.Inferior 


See also 


• Flow Document Overview 



How to: Enable Text Trimming 

3/6/2019 • 2 minutes to read ^ Edit Online 


This example demonstrates the usage and effects of the values available in the TextTrimming enumeration. 

Example 

The following example defines a TextBlock element with the TextTrimming attribute set. 

<TextBlocl< 

Name="myTextBlock" 

Margin="20" Backgr'ound="LightGoldenrodYellow" 

TextTr'imming="WordEllipsis" TextWr'apping="NoWrap" 

FontSize="14" 

> 

OnecLineBneak/x 
two twoxLineBneak/x 
Three Three Three<LlneBreak/> 
four four four four<LineBreak/> 

Five Five Five Five Five<LineBreak/> 
six six six six six six<LineBreak/> 

Seven Seven Seven Seven Seven Seven Seven 
</TextBlock> 


Setting the corresponding TextTrimming property in code is demonstrated below. 


myTextBlock.TextTrimming = TextTrimming.CharacterFllipsisj 


myTextBlock.TextTrimming = TextTrimming.CharacterFllipsis 


There are currently three options for trimming text: CharacterEllipsis, WordEllipsis, and None. 

When TextTrimming is set to CharacterEllipsis, text is trimmed and continued with an ellipsis at the character 
closest to the trimming edge. This setting tends to trim text to fit more closely to the trimming boundary, but may 
result in words being partially trimmed. The following figure shows the effect of this setting on a TextBlock similar 
to the one defined above. 


One 
two ttvo 
Three Thre... 
four four fo... 
Five Five Fi... 
six six six si... 
Seven Seve... 


When TextTrimming is set to WordEllipsis, text is trimmed and continued with an ellipsis at the end of the first full 
word closest to the trimming edge. This setting will not show partially trimmed words, but tends not to trim text as 
closely to the trimming edge as the CharacterEllipsis setting. The following figure shows the effect of this setting 
on the TextBlock defined above. 






One 
two ttvo 
Three- 
four four... 
Five Five... 
six sLx six... 
Seven... 


When TextTrimming is set to None, no text trimming is performed. In this case, text is simply cropped to the 
boundary of the parent text container. The following figure shows the effect of this setting on a TextBlock similar to 
the one defined above. 


One 
two hvo 
Three Three 1 
four four four 
Five Five Five 
SLX six SLX six ‘ 
Seven Seven S 
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The following example shows how to use two TextPointer objects to specify a range within text to apply a Span 
element to. 

Example 

using System; 
using System.Windows; 
using System.Windows.Media; 
using System.Windows.Controls; 
using System.Windows.Documents; 

namespace SDKSample 

{ 

public partial class InsertInlineIntoTextExample : Page 

{ 

public InsertInlineIntoTextExampleO 

{ 

// Create a paragraph with a short sentence 

Paragraph myParagraph = new Paragraph(new Run("Neptune has 72 times Earth's volume...")); 

// Create two TextPointers that will specify the text range the Span will cover 
TextPointer myTextPointerl = myParagraph.ContentStart.GetPositionAtOffset(10); 

TextPointer myTextPointer2 = myParagraph.ContentEnd.GetPositionAt0ffset(-5); 

// Create a Span that covers the range between the two TextPointers. 

Span mySpan = new Span(myTextPointerl, myTextPointer2); 
mySpan.Background = Brushes.Red; 

// Create a FlowDocument with the paragraph as its initial content. 

FlowDocument myFlowDocument = new FlowDocument(myParagraph); 

this.Content = myFlowDocument; 

} 

} 

} 





Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Controls 
Imports System.Windows.Documents 

Namespace SDKSample 

Partial Public Class InsertInlineIntoTextExample 
Inherits Page 
Public Sub New() 

' Create a paragraph with a short sentence 

Dim myParagraph As New Paragraph(New Run("Neptune has 72 times Earth's volume...")) 

' Create two TextPointers that will specify the text range the Span will cover 
Dim myTextPointerl As TextPointer = myParagraph.ContentStart.GetPositionAtOffset(10) 
Dim myTextPointer2 As TextPointer = myParagraph.ContentEnd.GetPositionAt0ffset(-5) 

' Create a Span that covers the range between the two TextPointers. 

Dim mySpan As New Span(myTextPointerlj myTextPointer2) 
mySpan.Background = Brushes.Red 

' Create a FlowDocument with the paragraph as its initial content. 

Dim myElowDocument As New ElowDocument(myParagraph) 

Me.Content = myElowDocument 

End Sub 
End Class 
End Namespace 


The illustration below shows what this example looks like. 

Neptune h^s 72 times Earth's volume... 


See also 


• Flow Document Overview 
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These examples demonstrate some of the more common operations that can be performed on flow content 
elements through the Blocks property. This property is used to add and remove items from BlockCollection. Flow 
content elements that feature a Blocks property include: 

• Figure 

• Floater 

• Listitem 

• Section 

• TableCell 

These examples happen to use Section as the flow content element, but these techniques are applicable to all 
elements that host a flow content element collection. 

Example 

The following example creates a new Section and then uses the Add method to add a new Paragraph to the 
Section contents. 

Section secx = new Section(); 

secx.Blocks.Add(new Paragnaph(new Run("A bit of text content..."))); 


Dim secx As New Section() 

secx.Blocks.Add(New Paragnaph(New Run("A bit of text content..."))) 


Example 

The following example creates a new Paragraph element and inserts it at the beginning of the Section. 

Paragraph parx = new Paragraph(new Run("Text to insert...")); 
secx.Blocks.InsertBefore(secx.Blocks.FirstBlock, parx); 


Dim parx As New Paragraph(New Run("Text to insert...")) 
secx.Blocks.InsertBefore(secx.Blocks.FirstBlock, parx) 


Example 

The following example gets the number of top-level Block elements contained in the Section. 

int countTopLevelBlocks = secx.Blocks.Count; 







Dim countTopLevelBlocks As Integer = secx.Blocks.Count 


Example 

The following example deletes the last Block element in the Section. 


secx.Blocks.Remove(secx.Blocks.LaStBlock); 


secx.Blocks.Remove(secx.Blocks.LaStBlock) 


Example 

The following example clears all of the contents (Block elements) from the Section, 
secx. Blocks. ClearO; 


secx.Blocks.Clear0 


See also 

• BlockCollection 

• InlineCollection 

• ListItemCollection 

• Flow Document Overview 

• Manipulate a Table's Row Groups through the RowGroups Property 

• Manipulate a Table's Columns through the Columns Property 

• Manipulate a Table's Row Groups through the RowGroups Property 
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These examples demonstrate some of the more common operations that can be performed on inline flow content 
elements (and containers of such elements, such as TextBlock) through the Inlines property. This property is used 
to add and remove items from InlineCollection. Flow content elements that feature an Inlines property include: 

• Bold 

• Hyperlink 

• Italic 

• Paragraph 

• Span 

• Underline 

These examples happen to use Span as the flow content element, but these techniques are applicable to all 
elements or controls that host an InlineCollection collection. 

Example 

The following example creates a new Span object, and then uses the Add method to add two text runs as content 
children of the Span. 

Span spanx = new Span(); 

spanx.Inlines.Add(new Run("A bit of text content...")); 
spanx.Inlines.Add(new Run("A bit more text content...")); 


Dim spanx As New Span() 

spanx.Inlines.Add(New Run("A bit of text content...")) 
spanx.Inlines.Add(New Run("A bit more text content...")) 


Example 

The following example creates a new Run element and inserts it at the beginning of the Span. 


Run runx = new Run("Text to insert..."); 

spanx.Inlines.InsertBefore(spanx.Inlines.FirstInlinej runx); 


Dim runx As New Run("Text to insert...") 

spanx.Inlines.InsertBefore(spanx.Inlines.FirstInlinej runx) 


Example 


The following example gets the number of top-level Inline elements contained in the Span. 






int countTopLevellnlines = spanx.Inlines.Countj 


Dim countTopLevellnlines As Integer = spanx.Inlines.Count 


Example 

The following example deletes the last Inline element in the Span. 


spanx.Inlines.Remove(spanx.Inlines.Lastinline)j 


spanx.Inlines.Remove(spanx.Inlines.Lastinline) 


Example 

The following example clears all of the contents (Inline elements) from the Span. 

spanx.Inlines.Clear(); 


spanx.Inlines.Clear() 


See also 

• BlockCollection 

• InlineCollection 

• ListItemCollection 

• Flow Document Overview 

• Manipulate a FlowDocument through the Blocks Property 

• Manipulate a Table's Columns through the Columns Property 

• Manipulate a Table's Row Groups through the RowGroups Property 






How to: Manipulate a FlowDocument through the 
Blocks Property 

4/8/2019 • 2 minutes to read i Edit Online 


These examples demonstrate some of the more common operations that can be performed on a FlowDocument 
through the Blocks property. 

Example 

The following example creates a new FlowDocument and then appends a new Paragraph element to the 
FlowDocument. 


FlowDocument flowDoc = new FlowDocument(new Paragraph(new Run("A bit of text content..."))); 
flowDoc.Blocks.Add(new Paragraph(new Run("Text to append..."))); 


Dim flowDoc As Mew FlowDocument(New Paragraph(New Run("A bit of text content..."))) 
flowDoc.Blocks.Add(New Panagraph(New Run("Text to append..."))) 


Example 

The following example creates a new Paragraph element and inserts it at the beginning of the FlowDocument. 


Paragraph p = new Paragraph(new Run("Text to insert...")); 
flowDoc.Blocks.InsertBefore(flowDoc.Blocks.FirstBlock, p); 


Dim p As New Paragraph(New Run("Text to insert...")) 
flowDoc.Blocks.InsertBefore(flowDoc.Blocks.FirstBlock, p) 


Example 

The following example gets the number of top-level Block elements contained in the FlowDocument. 

int countTopLevelBlocks = flowDoc.Blocks.Count; 


Dim countTopLevelBlocks As Integer = flowDoc.Blocks.Count 


Example 

The following example deletes the last Block element in the FlowDocument. 

flowDoc.Blocks.Remove(flowDoc.Blocks.LastBlock); 








flowDoc. Blocks. Reniove(flowDoc. Blocks. LastBlock) 


Example 

The following example clears all of the contents (Block elements) from the FlowDocument. 
flowDoc. Blocks. CleanO; 

flowDoc. Blocks. CleanO 


See also 

• Manipulate a Table's Row Groups through the RowGroups Property 

• Manipulate a Table's Columns through the Columns Property 

• Manipulate a Table's Row Groups through the RowGroups Property 
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This example demonstrates some of the more common operations that can be performed on a table's columns 
through the Columns property. 

Example 

The following example creates a new table and then uses the Add method to add columns to the table's Columns 
collection. 


Table tbl = new Table(); 
int columnsToAdd = 4; 
for (int X = 0; X < columnsToAdd; x++) 
tbl.Columns.Add(new TableColumn()); 


Dim tbl As New Table() 

Dim columnsToAdd As Integer = 4 
For X As Integer = 0 To columnsToAdd - 1 
tbl.Columns.Add(New TableColumn()) 
Next X 


Example 

The following example inserts a new TableColumn. The new column is inserted at index position 0, making it the 
new first column in the table. 


NOTE 

The TableColumnCollection collection uses standard zero-based indexing. 


tbl.Columns.Insert(0, new TableColumn()); 


tbl.Columns.Insert(0j New TableColumn()) 


Example 

The following example accesses some arbitrary properties on columns in the TableColumnCollection collection, 
referring to particular columns by index. 

tbl.Columns[0].Width = new GridLength(20); 
tbl.Columns[l].Background = Brushes.AliceBlue; 
tbl.Columns[2].Width = new GridLength(20); 
tbl.Columns[3].Background = Brushes.AliceBlue; 








tbl.Columns(0) .Width = New Gr'idLength(20) 
tbl.Columns(l).Background = Brushes.AliceBlue 
tbl.Columns(2).Width = New GridLength(20) 
tbl.Columns(3).Background = Brushes.AliceBlue 


Example 

The following example gets the number of columns currently hosted by the table. 

int columns = tbl.Columns.Count; 


Dim columns As Integer = tbl.Columns.Count 


Example 

The following example removes a particular column by reference, 
tbl.Columns.Remove(tbl.Columns[3]); 


tbl.Columns.Remove(tbl.Columns(3)) 


Example 

The following example removes a particular column by index, 
tbl.Columns.RemoveAt (2); 


tbl.Columns.RemoveAt(2) 


Example 

The following example removes all columns from the table's columns collection. 

tbl.Columns.ClearO; 


t bl. Column s.ClearO 


See also 

• Table Overview 

• Define a Table with XAML 

• Build a Table Programmatically 

• Manipulate a Table's Row Groups through the RowGroups Property 

• Manipulate a FlowDocument through the Blocks Property 

• Manipulate a Table's Row Groups through the RowGroups Property 
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This example demonstrates some of the more common operations that can be performed on a table's row 
groups through the RowGroups property. 

Example 

The following example creates a new table and then uses the Add method to add columns to the table's 
RowGroups collection. 

Table tbl = new Table(); 
int nowGnoupsToAdd = 4; 
for (int X = 0; X < rowGroupsToAdd; x++) 
tbl.RowGroups.Add(new TableRowGroup()); 


Dim tbl As New Table() 

Dim rowGroupsToAdd As Integer = 4 
For X As Integer = 0 To rowGroupsToAdd - 1 
tbl.RowGroups.Add(New TableRowGroup()) 
Next X 


Example 

The following example inserts a new TableRowGroup. The new column is inserted at index position 0, making it 
the new first row group in the table. 


NOTE 

The TableRowGroupCollection collection uses standard zero-based indexing. 


tbl.RowGroups.Insert(0j new TableRowGroupO); 


tbl.RowGroups.Insert(0j New TableRowGroupO) 


Example 

The following example adds several rows to a particular TableRowGroup (specified by index) in the table. 

int rowsToAdd = 10; 

for (int X = 0; X < rowsToAdd; x++) 

tbl.RowGroups[0].Rows.Add(new TableRow()); 








Dim nowsToAdd As Integer = 10 

For X As Integer = 0 To rowsToAdd - 1 

tbl.RowGroups(0).Rows.Add(New TableRow()) 
Next X 


Example 

The following example accesses some arbitrary properties on rows in the first row group in the table. 

// Alias the working TableRowGroup for ease in referencing. 

TableRowGroup trg = tbl.RowGroups[0]; 
trg.Rows[0].Background = Brushes.CornflowerBlue; 
trg.Rows[l].FontSize = 24 ; 
trg.Rows[2].ToolTip = "This row's tooltip"; 


' Alias the working TableRowGroup for ease in referencing. 

Dim trg As TableRowGroup = tbl.RowGroups(0) 

trg.Rows(0).Background = Brushes.CornflowerBlue 

trg.Rows(l).FontSize = 24 

trg.Rows(2).ToolTip = "This row's tooltip" 


Example 

The following example adds several cells to a particular TableRow (specified by index) in the table. 

int cellsToAdd = 10; 

for (int X = 0; X < cellsToAdd; x++) 

tbl.RowGroups[0].Rows[0].Cells.Add(new TableCell(new Paragraph(new Run("Cell " + (x + 1))))); 


Dim cellsToAdd As Integer = 10 

For X As Integer = 0 To cellsToAdd - 1 

tbl.RowGroups(0).Rows(0).Cells.Add(New TableCell(New Paragraph(New Run("Cell " & (x + 1))))) 
Next X 


Example 

The following example access some arbitrary methods and properties on cells in the first row in the first row 
group. 

// Alias the working for for ease in referencing. 

TableRow row = tbl.RowGroups[0].Rows[0]; 
row.Cells[0].Background = Brushes.PapayaWhip; 
row.Cells[l].FontStyle = FontStyles.Italic; 

// This call clears all of the content from this cell. 
row.Cells[2].Blocks.Clear(); 


' Alias the working for for ease in referencing. 

Dim row As TableRow = tbl.RowGroups(0).Rows(0) 
row.Cells(0).Background = Brushes.PapayaWhip 
row.Cells(l).FontStyle = FontStyles.Italic 
' This call clears all of the content from this cell. 
row.Cells(2).Blocks.Clear() 






Example 

The following example returns the number of TableRowGroup elements hosted by the table. 

int nowGroups = tbl.RowGnoups.Count; 


Dim nowGnoups As Integer = tbl.RowGroups.Count 


Example 

The following example removes a particular row group by reference, 
tbl.RowGroups.Remove(tbl.RowGroups[0]); 


tbl.RowGroups.Remove(tbl.RowGroups(0)) 


Example 

The following example removes a particular row group by index, 
tbl.RowGroups.RemoveAt(0); 


tbl.RowGroups.RemoveAt(0) 


Example 


The following example removes all row groups from the table's row groups collection. 


tbl. RowGroups. Clear 0; 


tbl.RowGroups.ClearO 


See also 

• How-to: Manipulate Flow Content Elements through the Inlines Property 

• Manipulate a FlowDocument through the Blocks Property 

• Manipulate a Table's Columns through the Columns Property 
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The following example demonstrates declarative usage for various flow content elements and associated 
attributes. Elements and attributes demonstrated include: 

• Bold element 

• BreakPageBefore attribute 

• FontSize attribute 

• Italic element 

• LineBreak element 

• List element 

• Listitem element 

• Paragraph element 

• Run element 

• Section element 

• Span element 

• Variants attribute (superscript and subscript) 

• Underline element 

Example 

<FlowDocument 

xmlns="http: //schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

> 

<Paragraph FontSize="18">Flow Format Example</Paragraph> 

<Panagraph> 

Lorem ipsum dolor sit amet^ consectetuer adipiscing elitj sed diam nonummy 
nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi 
enim ad minim veniam^ quis nostrud exerci tation ullamcorper suscipit lobortis 
nisi ut aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

</Paragraph> 

<Paragraph> 

Lorem ipsum dolor sit amet, consectetuer adipiscing elitj sed diam nonummy nibh 
euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim 
ad minim veniam^ quis nostrud exerci tation ullamcorper suscipit lobortis nisi 
ut aliquip ex ea commodo consequat. Duis autem vel eum iriure. 

</Paragraph> 

<Paragraph FontSize="18">More flow elements</Paragraph> 

<Paragraph FontSize="15">Inline, font type and weight, and a List</Paragraph> 

<List> 

<ListItem><Paragraph>Listitem 1</Paragraph></Listltem> 

<ListItemxParagraphxListItem 2</Paragraph></ListItem> 

<ListItemxParagraphxListItem 3</Paragraphx/ListItem> 




<ListItemxParagraph>ListItem 4</Par'agraph></ListItem> 

<ListItemxParagraph>ListItem 5</Par'agraphx/ListItem> 

</List> 

<ParagraphxBold>Bolded</Boldx/Paragr'aph> 

<ParagraphxLlnderline>Llnderlined</Underlinex/Paragraph> 

<Par'agraphxBoldxLlnderline>Bolded and Llnderlined</Underlinex/Boldx/Paragraph> 

< Pa nagraphxltalic>ltalic</ltalicx/Paragraph > 

<ParagraphxSpan>The Span elementj no inherent rendering</Spanx/Paragraph> 

<ParagraphxRun>The Run elementj no inherent rendering</Runx/Paragraph> 

<Paragraph FontSize="15">Subscriptj Superscript</Paragraph> 

<Paragraph> 

<Run Typography.\/ariants="Superscript">This text is Superscripted.</Run> This text isn't. 
</Paragraph> 

<Paragraph> 

<Run Typography.\/ariants="Subscript">This text is Subscripted.</Run> This text isn't. 
</Paragraph> 

<Paragraph> 

If a font does not support a particular form (such as Superscript) a default font form will be 
displayed. 

</Paragraph> 

<Paragraph FontSize="15">BlockSj breaks, paragraph</Paragraph> 

<SectionxParagraph>A block section of text</Paragraphx/Section> 

<SectionxParagraph>Another block section of text</Paragraphx/Section> 

<ParagraphxLineBreak/x/Paragraph> 

<SectionxParagraph>. .. and another section, preceded by a LineBreak</Paragraphx/Section> 
<Section BreakPageBefore="True"/> 

<SectionxParagraph>... and another section, preceded by a PageBreak</Paragraphx/Section> 

<Paragraph>Finally, a paragraph. Note the break between this paragraph ...</Paragraph> 

<Paragraph Textlndent="25">... and this paragraph, and also the left indention.</Paragraph> 

<ParagraphxLineBreak/x/Paragraph> 


</FlowDocument> 
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This example shows how to use the column-separating features of a FlowDocument. 

Example 

The following example defines a FlowDocument, and sets the ColumnGap, ColumnRuleBrush, and 
ColumnRuleWidth attributes. The FlowDocument contains a single paragraph of sample content 


<FlowDocumentReader> 

<FlowDocument 
ColumnGap="20.0" 

ColumnRuleBnush="DodgerBlue" 

ColumnRuleWidth="5.0" 

ColumnWidth="140.0" 

> 

<Panagraph Backgnound="AntiqueWhlte" TextAlignment="Left"> 

This paragraph has the background set to antique white to make its 
boundaries obvious. 

The column gap is the space between columns; this FlowDocument will 
have a column gap of 20 device-independend pixels. The column rule 
is a vertical line drawn in the column gapj and is used to visually 
separate columns; this FlowDocument a Dodger-blue column rule that 
is 5 pixels wide. 

The column rule and column gap both take space between columns. In 
this case, a column gap width of 20 plus a column rule of width of 5 
results in the space between columns being 25 pixels wide, 5 pixels 
for the column rule, and 10 pixels of column gap on either side of the column rule. 
</Paragraph> 

</FlowDocument> 

</FlowDocumentReader> 


The following figure shows the effects of the ColumnGap, ColumnRuleBrush, and ColumnRuleWidth attributes in a 
rendered FlowDocument. 


This paragraph has the 
background set to 
antique white to make 
its boundaries ob\ious. 
The column gap is the 
space between 
columns; this 
FlowDocument isill 
have a column gap of 
20 device-independend 
pixels. The column rule 
is a vertical line drawn 


in the column gap, and 
is used to I’isualty 
separate columns; this 
FlowDocument a 
Dodger-blue column 
rule that is 5 pixels 
wide. The column rule 
and column gap both 
take space betiveen 
columns. In this case, a 
column gap width of 20 
plus a column rule of 


tsidth of 5 results in the 
space betiveen columns 
being 25 pLxels wide, 5 
pLxels for the column 
rule, and 10 pixels of 
column gap on either 
side of the column rule. 
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Windows Presentation Foundation (WPF) includes support for rich presentation of text content. Text in WPF is 
rendered using Microsoft ClearType, which enhances the clarity and readability of text. WPF also supports 
OpenType fonts, which provide additional capabilities beyond those defined by the TrueType® format. 

In This Section 

Typography in WPF 
ClearType Overview 
ClearType Registry Settings 
Drawing Formatted Text 
Advanced Text Formatting 
Fonts 
Glyphs 

Flow-to Topics 

See also 

• Typography 

• Documents in WPF 

• OpenType Font Features 

• Optimizing WPF Application Performance 
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This topic introduces the major typographic features of WPF. These features include improved quality and 
performance of text rendering, OpenType typography support, enhanced international text, enhanced font 
support, and new text application programming interfaces (APIs). 

Improved Quality and Performance of Text 

Text in WPF is rendered using Microsoft ClearType, which enhances the clarity and readability of text. ClearType is 
a software technology developed by Microsoft that improves the readability of text on existing LCDs (Liquid 
Crystal Displays), such as laptop screens. Pocket PC screens and flat panel monitors. ClearType uses sub-pixel 
rendering which allows text to be displayed with a greater fidelity to its true shape by aligning characters on a 
fractional part of a pixel. The extra resolution increases the sharpness of the tiny details in text display, making it 
much easier to read over long durations. Another improvement of ClearType in WPF is y-direction anti-aliasing, 
which smoothes the tops and bottoms of shallow curves in text characters. For more details on ClearType 
features, see ClearType Overview. 



Text with ClearType y-direction antialiasing 

The entire text rendering pipeline can be hardware-accelerated in WPF provided your machine meets the 
minimum level of hardware required. Rendering that cannot be performed using hardware falls back to software 
rendering. Hardware-acceleration affects all phases of the text rendering pipeline—from storing individual 
glyphs, compositing glyphs into glyph runs, applying effects, to applying the ClearType blending algorithm to the 
final displayed output. For more information on hardware acceleration, see Graphics Rendering Tiers. 

Glyph 

Cache 



In addition, animated text, whether by character or glyph, takes full advantage of the graphics hardware 
capability enabled by WPF This results in smooth text animation. 

Rich Typography 

The OpenType font format is an extension of the TrueType® font format. The OpenType font format was 
developed jointly by Microsoft and Adobe, and provides a rich assortment of advanced typographic features. The 
Typography object exposes many of the advanced features of OpenType fonts, such as stylistic alternates and 



















swashes. The Windows SDK provides a set of sample OpenType fonts that are designed with rich features, such 
as the Pericles and Pescadero fonts. For more information, see Sample OpenType Font Pack. 


The Pericles OpenType font contains additional glyphs that provide stylistic alternates to the standard set of 
glyphs. The following text displays stylistic alternate glyphs. 


ANCIENT CP.UK MYTHOLOGY 


Swashes are decorative glyphs that use elaborate ornamentation often associated with calligraphy. The following 
text displays standard and swash glyphs for the Pescadero font. 

ABCDEFGHIJKLMN 

A'3 

For more details on OpenType features, see OpenType Font Features. 

Enhanced International Text Support 

WPF provides enhanced international text support by providing the following features: 

• Automatic line-spacing in all writing systems, using adaptive measurement. 

• Broad support for international text. For more information, see Globalization for WPF. 

• Language-guided line breaking, hyphenation, and justification. 

Enhanced Font Support 

WPF provides enhanced font support by providing the following features: 

• Unicode for all text. Font behavior and selection no longer require charset or codepage. 

• Font behavior independent of global settings, such as system locale. 

• Separate FontWeight, FontStretch, and FontStyle types for defining a FontFamily. This provides greater 
flexibility than in Win32 programming, in which Boolean combinations of italic and bold are used to 
define a font family. 

• Writing direction (horizontal versus vertical) handled independent of font name. 

• Font linking and font fallback in a portable XML file, using composite font technology. Composite fonts 
allow for the construction of full range multilingual fonts. Composite fonts also provide a mechanism that 
avoids displaying missing glyphs. For more information, see the remarks in the FontFamily class. 

• International fonts built from composite fonts, using a group of single-language fonts. This saves on 
resource costs when developing fonts for multiple languages. 

• Composite fonts embedded in a document, thereby providing document portability. For more 
information, see the remarks in the FontFamily class. 

New Text Application Programming Interfaces (APIs) 

WPF provides several text APIs for developers to use when including text in their applications. These APIs are 
grouped into three categories: 

• Layout and user interface. The common text controls for the graphical user interface (GUI). 


• Lightweight text drawing. Allows you to draw text directly to objects. 

• Advanced text formatting. Allows you to implement a custom text engine. 

Layout and User Interface 

At the highest level of functionality, the text APIs provide common user interface (Ul) controls such as Label, 
TextBlock, and TextBox. These controls provide the basic Ul elements within an application, and offer an easy way 
to present and interact with text. Controls such as RichTextBox and PasswordBox enable more advanced or 
specialized text-handling. And classes such as TextRange, TextSelection, and TextPointer enable useful text 
manipulation. These Ul controls provide properties such as FontFamily, FontSize, and FontStyle, which enable you 
to control the font that is used to render the text. 

Using Bitmap Effects, Transforms, and Text Effects 

WPF allows you to create visually interesting uses of text by uses features such as bitmap effects, transforms, and 
text effects. The following example shows a typical type of a drop shadow effect applied to text. 

Shadow Text 


The following example shows a drop shadow effect and noise applied to text. 

SriFiclovv Texi; 

The following example shows an outer glow effect applied to text. 

Shadow Text 


The following example shows a blur effect applied to text. 

Shadow Text 


The following example shows the second line of text scaled by 150% along the x-axis, and the third line of text 
scaled by 150% along the y-axis. 

Scaled Text 

Scaled Text 

Scaled Text 

The following example shows text skewed along the x-axis. 

Skewed Text 


A TextEffect object is a helper object that allows you to treat text as one or more groups of characters in a text 
string. The following example shows an individual character being rotated. Each character is rotated 
independently at 1 -second intervals. 


Windo^ s Vista 


Using Flow Documents 

In addition to the connnnon Ul controls, WPF offers a layout control for text presentation—the FlowDocument 
element. The FlowDocument element, in conjunction with the DocumentViewer element, provides a control for 
large amounts of text with varying layout requirements. Layout controls provide access to advanced typography 
through the Typography object and font-related properties of other Ul controls. 

The following example shows text content hosted in a FlowDocumentReader, which provides search, navigation, 
pagination, and content scaling support. 


~~) Using OpenType Fonts Sample 
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Kaotenay | Lindsey | Miramonte | Miramonte Bold 

Pericles 

Pericles Light | Pescadero | Pescadero Bold 




1 

Pericles 

1I34S67890 

([{@}]) 

/|\$% 

Characters 

ABCDEFCHIJKLMNOP 

QhSTUVWXYZ 

ABCDEFGHIJKLMNOPQ 

RSTUVWXYZ 

Stylistic Alternates 

ANCKNT 

MYTHOLOGY 

CWiiK 


Type text to find.. 
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For more information, see Documents in WPF. 

Lightweight Text Drawing 

You can draw text directly to WPF objects by using the DrawText method of the DrawingContext object. To use 
this method, you create a FormattedText object. This object allows you to draw multi-line text, in which each 
character in the text can be individually formatted. The functionality of the FormattedText object contains much of 
the functionality of the DrawText flags in the Windows API. In addition, the FormattedText object contains 
functionality such as ellipsis support, in which an ellipsis is displayed when text exceeds its bounds. The following 
example shows text that has several formats applied to it, including a linear gradient on the second and third 
words. 

Lorem ipsum 

dolor sit amet, 
consectetur 
adipisicing elit, 
sed do eiusmod... 





























You can convert formatted text into Geometry objects, allowing you to create other types of visually interesting 
text. For example, you could create a Geometry object based on the outline of a text string. 
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The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, 
and highlight of converted text. 
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For more information on the FormattedText object, see Drawing Formatted Text. 

Advanced Text Formatting 

At the most advanced level of the text APIs, WPF offers you the ability to create custom text layout by using the 
TextFormatter object and other types in the System.Windows.Media.TextFormatting namespace. The 
TextFormatter and associated classes allow you to implement custom text layout that supports your own 
definition of character formats, paragraph styles, line breaking rules, and other layout features for international 
text. There are very few cases in which you would want to override the default implementation of the WPF text 
layout support. However, if you were creating a text editing control or application, you might require a different 
implementation than the default WPF implementation. 

Unlike a traditional text API, the TextFormatter interacts with a text layout client through a set of callback 
methods. It requires the client to provide these methods in an implementation of the TextSource class. The 
following diagram illustrates the text layout interaction between the client application and TextFormatter. 

Text to display 

The quick red fox jumped over the lazy broHn dog. 


Typeface j Verdana 
FontSize 
Foreground 
Indent 


Custom properties 



The quick red fox 
jumped over the 
lazy brown dog. 

For more details on creating custom text layout, see Advanced Text Formatting. 



See also 
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This topic provides an overview of the Microsoft ClearType technology found in the Windows Presentation 
Foundation (WPF). 

Technology Overview 

ClearType is a software technology developed by Microsoft that improves the readability of text on existing LCDs 
(Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. ClearType works by 
accessing the individual vertical color stripe elements in every pixel of an LCD screen. Before ClearType, the 
smallest level of detail that a computer could display was a single pixel, but with ClearType running on an LCD 
monitor, we can now display features of text as small as a fraction of a pixel in width. The extra resolution increases 
the sharpness of the tiny details in text display, making it much easier to read over long durations. 

The ClearType available in Windows Presentation Foundation (WPF) is the latest generation of ClearType which 
has several improvements over version found in Microsoft Windows Graphics Device Interface (GDI). 

Sub-pixel Positioning 

A significant improvement over the previous version of ClearType is the use of sub-pixel positioning. Unlike the 
ClearType implementation found in GDI, the ClearType found in Windows Presentation Foundation (WPF) allows 
glyphs to start within the pixel and not just the beginning boundary of the pixel. Because of this extra resolution in 
positioning glyphs, the spacing and proportions of the glyphs is more precise and consistent. 

The following two examples show how glyphs may begin on any sub-pixel boundary when sub-pixel positioning 
is used. The example on the left is rendered using the earlier version of the ClearType renderer, which did not 
employ sub-pixel positioning. The example on the right is rendered using the new version of the ClearType 
renderer, using sub-pixel positioning. Note how each e and I in the right-hand image is rendered slightly 
differently because each starts on a different sub-pixel. When viewing the text at its normal size on the screen, this 
difference is not noticeable because of the high contrast of the glyph image. This is only possible because of 
sophisticated color filtering that is incorporated in ClearType. 

Earlier version of ClearType 



Later version of ClearType 



Text displayed with earlier and later versions of ClearType 















The following two examples compare output from the earlier ClearType renderer with the new version of the 
ClearType renderer. The subpixel positioning, shown on the right, greatly improves the spacing of type on screen, 
especially at small sizes where the difference between a sub-pixel and a whole pixel represents a significant 
proportion of glyph width. Note that spacing between the letters is more even in the second image. The 
cumulative benefit of sub-pixel positioning to the overall appearance of a screen of text is greatly increased, and 
represents a significant evolution in ClearType technology. 

Earlier version of ClearType 



Text with earlier and later versions of ClearType 


Y-Direction Antialiasing 

Another improvement of ClearType in Windows Presentation Foundation (WPF) is y-direction anti-aliasing. The 
ClearType in GDI without y-direction anti-aliasing provides better resolution on the x-axis but not the y-axis. On 
the tops and bottoms of shallow curves, the jagged edges detract from its readability. 


The following example shows the effect of having no y-direction antialiasing. In this case, the jagged edges on the 
top and bottom of the letter are apparent. 




Enlarged view of Capitol 
Script D shows jagged 
edges on shallow curves 


Text with jagged edges on shallow curves 


ClearType in Windows Presentation Foundation (WPF) provides antialiasing on the y-direction level to smooth out 
any jagged edges. This is particularly important for improving the readability of East Asian languages where 
ideographs have an almost equal amount of horizontal and vertical shallow curves. 


The following example shows the effect of y-direction antialiasing. In this case, the top and bottom of the letter 

















show a smooth curve. 



ClearType with y-direction 
antialiasing smooths out the 
jagged edges on shallow 
curves and other y-directlon 
Features 



Text with ClearType y-direction antialiasing 


Hardware Acceleration 

ClearType in Windows Presentation Foundation (WPF) can take advantage of hardware acceleration for better 
performance and to reduce CPU load and system memory requirements. By using the pixel shaders and video 
memory of a graphics card, ClearType provides faster rendering of text, particularly when animation is used. 

ClearType in Windows Presentation Foundation (WPF) does not modify the system-wide ClearType settings. 
Disabling ClearType in Windows sets Windows Presentation Foundation (WPF) antialiasing to grayscale mode. In 
addition, ClearType in Windows Presentation Foundation (WPF) does not modify the settings of the ClearType 
Tuner PowerToy. 

One of the Windows Presentation Foundation (WPF) architectural design decisions is to have resolution 
independent layout better support higher resolution DPI monitors, which are becoming more widespread. This 
has the consequence of Windows Presentation Foundation (WPF) not supporting aliased text rendering or the 
bitmaps in some East Asian fonts because they are both resolution dependent. 

Further Information 

ClearType Information 
ClearType Tuner PowerToy 

See also 


ClearType Registry Settings 
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This topic provides an overview of the Microsoft ClearType registry settings that are used by WPF applications. 

Technology Overview 

WPF applications that render text to a display device use ClearType features to provide an enhanced reading 
experience. ClearType is a software technology developed by Microsoft that improves the readability of text on 
existing LCDs (Liquid Crystal Displays), such as laptop screens, Pocket PC screens and flat panel monitors. 

ClearType works by accessing the individual vertical color stripe elements in every pixel of an LCD screen. For 
more information on ClearType, see ClearType Overview. 

Text that is rendered with ClearType can appear significantly different when viewed on various display devices. For 
example, a small number of monitors implement the color stripe elements in blue, green, red order rather than the 
more common red, green, blue (RGB) order. 

Text that is rendered with ClearType can also appear significantly different when viewed by individuals with varying 
levels of color sensitivity. Some individuals can detect slight differences in color better than others. 

In each of these cases, ClearType features need to be modified in order to provide the best reading experience for 
each individual. 

Registry Settings 

WPF specifies four registry settings for controlling ClearType features: 


SETTING 

DESCRIPTION 

ClearType level 

Describes the level of ClearType color clarity. 

Gamma level 

Describes the level of the pixel color component for a display 
device. 

Pixel structure 

Describes the arrangement of pixels for a display device. 

Text contrast level 

Describes the level of contrast for displayed text. 


These settings can be accessed by an external configuration utility that knows how to reference the identified WPF 
ClearType registry settings. These settings can also be created or modified by accessing the values directly by using 
the Windows Registry Editor. 

If the WPF ClearType registry settings are not set (which is the default state), the WPF application queries the 
Windows system parameters information for font smoothing settings. 


NOTE 

For information on enumerating display device names, see the systemParametersinfo Win32 function. 


ClearType Level 





The ClearType level allows you to adjust the rendering of text based on the color sensitivity and perception of an 
individual. For some individuals, the rendering of text that uses ClearType at its highest level does not produce the 
best reading experience. 

The ClearType level is an integer value that ranges from 0 to 100. The default level is 100, which means ClearType 
uses the maximum capability of the color stripe elements of the display device. However, a ClearType level of 0 
renders text as gray scale. By setting the ClearType level somewhere between 0 and 100, you can create an 
intermediate level that is suitable to an individual's color sensitivity. 

Registry Setting 

The registry setting location for the ClearType level is an individual user setting that corresponds to a specific 
display device name; 


HKEY_CLIRRENT_USER\SOFTWARE\Microsoft\Avalon.Graphics\<displayName> 


For each display device name for a user, a ciearTypetevei DWORD value is defined. The following screenshot 
shows the Registry Editor setting for the ClearType level. 



NOTE 

WPF applications render text in one of either two modes, with and without ClearType. When text is rendered without 
ClearType, it is referred to as gray scale rendering. 


Gamma Level 

The gamma level refers to the nonlinear relationship between a pixel value and luminance. The gamma level 
setting should correspond to the physical characteristics of the display device; otherwise, distortions in rendered 
output may occur. For example, text may appear too wide or too narrow, or color fringes may appear on the edges 
of vertical stems of glyphs. 

The gamma level is an integer value that ranges from 1000 to 2200. The default level is 1900. 

Registry Setting 

The registry setting location for the gamma level is a local machine setting that corresponds to a specific display 
device name: 

HKEY_LOCAL_HACHINE\SOFTWARE\Micr'osoft\Avalon. Graphics\<displayName> 

For each display device name for a user, a Gammatevei DWORD value is defined. The following screenshot shows 
the Registry Editor setting for the gamma level. 
















Pixel Structure 

The pixel structure describes the type of pixels that make up a display device. The pixel structure is defined as one 
of three types: 

TYPE VALUE DESCRIPTION 


Flat 0 The display device has no pixel 

structure. This means that light sources 
for each color are spread equally on the 
pixel area—this is referred to as gray 
scale rendering. This is how a standard 
display device works. ClearType is never 
applied to the rendered text. 


RGB 1 The display device has pixels that 

consist of three stripes in the following 
order: red, green, and blue. ClearType is 
applied to the rendered text. 


BGR 2 The display device has pixels that 

consist of three stripes in the following 
order: blue, green, and red. ClearType is 
applied to the rendered text. Notice 
how the order is inverted from the RGB 
type. 


The pixel structure corresponds to an integer value that ranges from 0 to 2. The default level is 0, which represents 
a flat pixel structure. 


NOTE 

For information on enumerating display device names, see the EnumDlsplayOevices Win32 function. 


Registry Setting 

The registry setting location for the pixel structure is a local machine setting that corresponds to a specific display 
device name: 


HKEY_LOCAL_HACHINE\SOFTWARE\Micr'osoft\Avalon. Graphics\<displayName> 

For each display device name for a user, a Pixeistructure DWORD value is defined. The following screenshot 
shows the Registry Editor setting for the pixel structure. 















Text Contrast Level 

The text contrast level allows you to adjust the rendering of text based on the stem widths of glyphs. The text 
contrast level is an integer value that ranges from 0 to 6—the larger the integer value, the wider the stem. The 
default level is 1. 

Registry Setting 

The registry setting location for the text contrast level is an individual user setting that corresponds to a specific 
display device name: 


HKEY_CLIRRENT_USER\Software\Microsoft\Avalon.Graphics\<displayName> 


For each display device name for a user, a Textcontrastievei DWORD value is defined. The following screenshot 
shows the Registry Editor setting for the text contrast level. 



See also 


• ClearType Overview 

• ClearType Antialiasing 
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This topic provides an overview of the features of the FormattedText object. This object provides low-level control 
for drawing text in Windows Presentation Foundation (WPF) applications. 

Technology Overview 

The FormattedText object allows you to draw multi-line text, in which each character in the text can be individually 
formatted. The following example shows text that has several formats applied to it. 

Lorem ipsum 

dolor sit amet, 
consectetur 
adipisicing elit, 
sed do eiusmod... 


NOTE 

For those developers migrating from the Win32 API, the table in the Win32 Migration section lists the Win32 DrawText 
flags and the approximate equivalent in Windows Presentation Foundation (WPF). 


Reasons for Using Formatted Text 

WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and 
has its own list of features and limitations. In general, the TextBlock element should be used when limited text 
support is required, such as a brief sentence in a user interface (Ul). Label can be used when minimal text support 
is required. For more information, see Documents in WPF. 

The FormattedText object provides greater text formatting features than Windows Presentation Foundation (WPF) 
text controls, and can be useful in cases where you want to use text as a decorative element. For more 
information, see the following section Converting Formatted Text to a Geometry. 

In addition, the FormattedText object is useful for creating text-oriented DrawingVisual-derived objects. 
DrawingVisual is a lightweight drawing class that is used to render shapes, images, or text. For more information, 
see Hit Test Using DrawingVisuals Sample. 

Using the FormattedText Object 

To create formatted text, call the FormattedText constructor to create a FormattedText object. Once you have 
created the initial formatted text string, you can apply a range of formatting styles. 

Use the MaxTextWidth property to constrain the text to a specific width. The text will automatically wrap to avoid 
exceeding the specified width. Use the MaxTextHeight property to constrain the text to a specific height. The text 
will display an ellipsis,"..." for the text that exceeds the specified height. 





Lorem ipsum dolor 
sit amet, 
consectetur... 


Text wordwraps when it 
exceeds the width 

Text shows ellipsis when 
it exceeds the height 


adipisicing elit, sed do eiusmod tempor 


You can apply multiple formatting styles to one or more characters. For example, you could call both the 
SetFontSize and SetForegroundBrush methods to change the formatting of the first five characters in the text. 

The following code example creates a FormattedText object and then applies several formatting styles to the text. 

protected override void OnRender(DrawingContext drawingContext) 

{ 

string teststring = "Lorem ipsum dolor sit ametj consectetur adipisicing elitj sed do eiusmod tempor"; 

// Create the initial formatted text string. 

FormattedText formattedText = new FormattedText( 
testStringj 

CultureInfo.GetCultureInfo("en-us")j 
FlowDirection.LeftToRight^ 
new Typeface("Verdana"), 

32, 

Brushes.Black); 

// Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears. 
formattedText.MaxTextWidth = 300; 
formattedText.HaxTextHeight = 240; 

// Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters. 
// The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5); 

// Use a Bold font weight beginning at the 6th character and continuing for 11 characters. 
formattedText.SetFontWeight(FontWeights.Bold, 6, 11); 

// Use a linear gradient brush beginning at the 6th character and continuing for 11 characters. 
formattedText.SetForegroundBrush( 

new LinearGradientBrush( 

Colors.Orange, 

Colors.Teal, 

90.0), 

6 , 11 ); 

// Use an Italic font style beginning at the 28th character and continuing for 28 characters. 
formattedText.SetFontStyle(FontStyles.Italic, 28, 28); 

// Draw the formatted text string to the DrawingContext of the control. 
drawingContext.DrawText(formattedText, new Point(10, 0)); 





Protected Overrides Sub OnRender(By\/al drawingContext As DrawingContext) 

Dim teststring As String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor" 

' Create the initial formatted text string. 

Dim formattedText As New FormattedText(testStringj CultureInfo.GetCultureInfo("en-us"), 
FlowDirection.LeftToRight^ New Typeface("Verdana")j 32, Brushes.Black) 

' Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears. 
formattedText.HaxTextWidth = 300 
formattedText.MaxTextHeight = 240 

' Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters. 
' The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSlze(36 * (96.0 / 72.0), 0, 5) 

' Use a Bold font weight beginning at the 6th character and continuing for 11 characters. 
formattedText.SetFontWeight(FontWeights.Bold, 6, 11) 

' Use a linear gradient brush beginning at the 6th character and continuing for 11 characters. 
formattedText.SetForegroundBrush(New LinearGradientBrush(Colors.Orange, Colors.Teal, 90.0), 6, 11) 

' Use an Italic font style beginning at the 28th character and continuing for 28 characters. 
formattedText.SetFontStyle(FontStyles.Italic, 28, 28) 

' Draw the formatted text string to the DrawingContext of the control. 
drawingContext.DrawText(formattedText, New Point(10, 0)) 

End Sub 


Font Size Unit of Measure 

As with other text objects in Windows Presentation Foundation (WPF) applications, the FormattedText object uses 
device-independent pixels as the unit of measure. However, most Win32 applications use points as the unit of 
measure. If you want to use display text in units of points in Windows Presentation Foundation (WPF) 
applications, you need to convert device-independent units (1/96th inch per unit) to points. The following code 
example shows how to perform this conversion. 

// The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5)j 

' The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSize(36 * (96.0 / 72.0), 0, 5) 


Converting Formatted Text to a Geometry 

You can convert formatted text into Geometry objects, allowing you to create other types of visually interesting 
text. For example, you could create a Geometry object based on the outline of a text string. 




The following examples illustrate several ways of creating interesting visual effects by modifying the stroke, fill, 
and highlight of converted text. 
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When text is converted to a Geometry object, it is no longer a collection of characters—you cannot modify the 
characters in the text string. However, you can affect the appearance of the converted text by modifying its stroke 
and fill properties. The stroke refers to the outline of the converted text; the fill refers to the area inside the outline 
of the converted text. For more information, see Create Outlined Text. 

You can also convert formatted text to a PathGeometry object, and use the object for highlighting the text. For 
example, you could apply an animation to the PathGeometry object so that the animation follows the outline of 
the formatted text. 

The following example shows formatted text that has been converted to a PathGeometry object. An animated 
ellipse follows the path of the strokes of the rendered text. 

Hello World! 

Sphere following the path geometry of text 

For more information, see How to: Create a PathGeometry Animation for Text. 

You can create other interesting uses for formatted text once it has been converted to a PathGeometry object. For 
example, you can clip video to display inside it. 



Win32 Migration 

The features of FormattedText for drawing text are similar to the features of the Win32 DrawText function. For 
those developers migrating from the Win32 API, the following table lists the Win32 DrawText flags and the 
approximate equivalent in Windows Presentation Foundation (WPF). 


DRAWTEXT FLAG 

WPF EQUIVALENT 

NOTES 

DT_BOTTOM 

Height 

Use the Height property to compute 



an appropriate Win32 DrawText 'y' 



position. 







DRAWTEXT FLAG 


WPF EQUIVALENT 


NOTES 


DT_CALCRECT 

Height, Width 

Use the Height and Width properties 
to calculate the output rectangle. 

DT_CENTER 

TextAlignment 

Use the TextAlignment property with 
the value set to Center. 

DT_EDITCONTROL 

None 

Not required. Space width and last line 
rendering are the same as in the 
framework edit control. 

DT_END_ELLIPSIS 

Trimming 

Use the Trimming property with the 
value CharacterEllipsis. 

Use WordEllipsis to get Win32 
DT_END_ELLIPSIS with 
DT_WORD_ELIPSIS end ellipsis—in this 
case, character ellipsis only occurs on 
words that do not fit on a single line. 

DT_EXPAND_TABS 

None 

Not required. Tabs are automatically 
expanded to stops every 4 ems, which 
is approximately the width of 8 
language-independent characters. 

DT_EXTERNALLEADING 

None 

Not required. External leading is always 
included in line spacing. Use the 
LineHeight property to create user- 
defined line spacing. 

DT_HIDEPREFIX 

None 

Not supported. Ftemove the from 
the string before constructing the 
FormattedText object. 

DT_LEFT 

TextAlignment 

This is the default text alignment. Use 
the TextAlignment property with the 
value set to Left. (WPF only) 

DT_MODIFYSTRING 

None 

Not supported. 

DT_NOCLIP 

VisualClip 

Clipping does not happen 
automatically. If you want to clip text, 
use the VisualClip property. 

DT_NOFULLWIDTHCHARBREAK 

None 

Not supported. 

DT_NOPREFIX 

None 

Not required. The character in 
strings is always treated as a normal 
character. 

DT_PATH ELLIPSIS 

None 

Use the Trimming property with the 
value WordEllipsis. 


DRAWTEXT FLAG 


WPF EQUIVALENT 


NOTES 


DT_PREFIX 

None 

Not supported. If you want to use 
underscores for text, such as an 
accelerator key or link, use the 
SetTextDecorations method. 

DT_PREFIXONLY 

None 

Not supported. 

DT_ RIGHT 

TextAlignment 

Use the TextAlignment property with 
the value set to Right. (WPF only) 

DT_RTLREADING 

FlowDirection 

Set the FlowDirection property to 
RightToLeft. 

DT_SINGLELINE 

None 

Not required. FormattedText objects 
behave as a single line control, unless 
either the MaxTextWidth property is set 
or the text contains a carriage 
return/line feed (CR/LF). 

DT_TABSTOP 

None 

No support for user-defined tab stop 
positions. 

DT_TOP 

Height 

Not required. Top justification is the 
default. Other vertical positioning 
values can be defined by using the 
Height property to compute an 
appropriate Win32 DrawText 'y' 
position. 

DT_VCENTER 

Height 

Use the Height property to compute 
an appropriate Win32 DrawText 'y' 
position. 

DT_WORD BREAK 

None 

Not required. Word breaking happens 
automatically with FormattedText 
objects. You cannot disable it. 

DT_WORD_ELLIPSIS 

Trimming 

Use the Trimming property with the 


value WordEllipsis. 


See also 

• FormattedText 

• Documents in WPF 

• Typography in WPF 

• Create Outlined Text 

• How to: Create a PathGeometry Animation for Text 
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Windows Presentation Foundation (WPF) provides a robust set of APIs for including text in your application. 

Layout and user interface (Ul) APIs, such as TextBlock, provide the most common and general-use elements for text 
presentation. Drawing APIs, such as GlyphRunDrawing and FormattedText, provide a means for including 
formatted text in drawings. At the most advanced level, WPF provides an extensible text formatting engine to 
control every aspect of text presentation, such as text store management, text run formatting management, and 
embedded object management. 

This topic provides an introduction to WPF text formatting. It focuses on client implementation and use of the WPF 
text formatting engine. 


NOTE 

All code examples within this document can be found in the Advanced Text Formatting Sample. 


Prerequisites 

This topic assumes that you are familiar with the higher level APIs used for text presentation. Most user scenarios 
will not require the advanced text formatting APIs discussed in this topic. For an introduction to the different text 
APIs, see Documents in WPF. 

Advanced Text Formatting 

The text layout and Ul controls in WPF provide formatting properties that allow you to easily include formatted 
text in your application. These controls expose a number of properties to handle the presentation of text, which 
includes its typeface, size, and color. Under ordinary circumstances, these controls can handle the majority of text 
presentation in your application. However, some advanced scenarios require the control of text storage as well as 
text presentation. WPF provides an extensible text formatting engine for this purpose. 

The advanced text formatting features found in WPF consist of a text formatting engine, a text store, text runs, and 
formatting properties. The text formatting engine, TextFormatter, creates lines of text to be used for presentation. 
This is achieved by initiating the line formatting process and calling the text formatter's FormatLine. The text 
formatter retrieves text runs from your text store by calling the store's GetTextRun method. The TextRun objects are 
then formed into TextLine objects by the text formatter and given to your application for inspection or display. 

Using the Text Formatter 

TextFormatter is the WPF text formatting engine and provides services for formatting and breaking text lines. The 
text formatter can handle different text character formats and paragraph styles, and includes support for 
international text layout. 

Unlike a traditional text API, the TextFormatter interacts with a text layout client through a set of callback methods. 
It requires the client to provide these methods in an implementation of the TextSource class. The following 
diagram illustrates the text layout interaction between the client application and TextFormatter. 





Text to display 



The quick red fox 
jumped over the 
lazy brown dog. 


The text formatter is used to retrieve formatted text lines from the text store, which is an implementation of 
TextSource. This is done by first creating an instance of the text formatter by using the Create method. This method 
creates an instance of the text formatter and sets the maximum line height and width values. As soon as an 
instance of the text formatter is created, the line creation process is started by calling the FormatLine method. 
TextFormatter calls back to the text source to retrieve the text and formatting parameters for the runs of text that 
form a line. 

In the following example, the process of formatting a text store is shown. The TextFormatter object is used to 
retrieve text lines from the text store and then format the text line for drawing into the DrawingContext. 















// Create a DrawingGroup object for storing formatted text. 
textDest = new DrawingGroup(); 

DrawingContext dc = textDest.Open(); 

// Update the text store. 

_textStore.Text = textToFormat.Text; 

_textStore.FontRendering = _currentRenderlngj 

// Create a TextFormatter object. 

TextFormatter formatter = TextFormatter.Create(); 

// Format each line of text from the text store and draw it. 
while (textStorePosition < _textStore.Text.Length) 

{ 

// Create a textline from the text store using the TextFormatter object, 
using (TextLine myTextLine = formatter.FormatLine( 

_textStorej 

textStorePosition^ 

96*6, 

new GenericTextParagraphProperties(_currentRendering), 
null)) 

{ 

// Draw the formatted text into the drawing context. 
myTextLine.Draw(dc, linePosition, InvertAxes.None); 

// Update the index position in the text store. 
textStorePosition += myTextLine.Length; 

// Update the line position coordinate for the displayed line. 
linePosition. Y += myTextLine. Fleight; 

} 

} 

// Persist the drawn text content. 
dc.CloseO; 

// Display the formatted text in the DrawingGroup object. 
myDrawingBrush.Drawing = textDest; 






' Create a DrawingGroup object for storing formatted text. 
textDest = New DrawingGroup() 

Dim dc As DrawingContext = textDest.Open() 

' Update the text store. 

_textStore.Text = textToFormat.Text 
_textStore.FontRendering = _currentRendering 

' Create a TextFormatter object. 

Dim formatter As TextFormatter = TextFormatter.Create() 

' Format each line of text from the text store and draw it. 

Do While textStorePosition < _textStore.Text.Length 

' Create a textline from the text store using the TextFormatter object. 

Using myTextLine As TextLine = formatter.FormatLine(_textStorej textStorePositionj 96*6j New 
GenericTextParagraphProperties(_currentRendering)j Nothing) 

' Draw the formatted text into the drawing context. 
myTextLine.Draw(dCj linePosition^ InvertAxes.None) 

' Update the index position in the text store. 
textStorePosition += myTextLine.Length 

' Update the line position coordinate for the displayed line. 
linePosition.Y += myTextLine.Height 
End Using 
Loop 

' Persist the drawn text content. 
dc.CloseO 

' Display the formatted text in the DrawingGroup object. 
myDrawingBrush.Drawing = textDest 


Implementing the Client Text Store 

When you extend the text formatting engine, you are required to implement and manage all aspects of the text 
store. This is not a trivial task. The text store is responsible for tracking text run properties, paragraph properties, 
embedded objects, and other similar content. It also provides the text formatter with individual TextRun objects 
which the text formatter uses to create TextLine objects. 

To handle the virtualization of the text store, the text store must be derived from TextSource. TextSource defines the 
method the text formatter uses to retrieve text runs from the text store. GetTextRun is the method used by the text 
formatter to retrieve text runs used in line formatting. The call to GetTextRun is repeatedly made by the text 
formatter until one of the following conditions occurs: 

• A TextEndOfLine or a subclass is returned. 

• The accumulated width of text runs exceeds the maximum line width specified in either the call to create the 
text formatter or the call to the text formatter's FormatLine method. 

• A Unicode newline sequence, such as "CF", "LF", or "CRLF", is returned. 

Providing Text Runs 

The core of the text formatting process is the interaction between the text formatter and the text store. Your 
implementation of TextSource provides the text formatter with the TextRun objects and the properties with which 
to format the text runs. This interaction is handled by the GetTextRun method, which is called by the text formatter. 

The following table shows some of the predefined TextRun objects. 



TEXTRUN TYPE 


USAGE 


TextCharacters 

The specialized text run used to pass a representation of 
character glyphs back to the text formatter. 

TextEmbeddedObJect 

The specialized text run used to provide content in which 
measuring, hit testing, and drawing is done in whole, such as 
a button or image within the text. 

TextEndOfLine 

The specialized text run used to mark the end of a line. 

TextEndOfParagraph 

The specialized text run used to mark the end of a paragraph. 

TextEndOfSegment 

The specialized text run used to mark the end of a segment, 
such as to end the scope affected by a previous TextModifier 

run. 

TextHidden 

The specialized text run used to mark a range of hidden 
characters. 


TextModifier The specialized text run used to modify properties of text runs 

in its scope. The scope extends to the next matching 
TextEndOfSegment text run, or the next TextEndOfParagraph. 

Any of the predefined TextRun objects can be subclassed. This allows your text source to provide the text formatter 
with text runs that include custom data. 

The following example demonstrates a GetTextRun method. This text store returns TextRun objects to the text 
formatter for processing. 

// Used by the TextFormatter' object to r'etrieve a run of text from the text source, 
public override TextRun GetTextRun(int textSourceCharacterIndex) 

{ 

// Make sure text source index is in bounds, 
if (textSourceCharacterIndex < 0) 

throw new ArgumentOutOfRangeException("textSourceCharacterIndex"j "Value must be greater than 0."); 
if (textSourceCharacterIndex >= _text.Length) 

{ 

return new TextEndOfParagraph(l); 

} 

// Create TextCharacters using the current font rendering properties, 
if (textSourceCharacterIndex < _text.Length) 

{ 

return new TextCharacters( 

_text, 

textSourceCharacterIndex, 

_text.Length - textSourceCharacterIndex, 

new GenericTextRunProperties(_currentRendering)); 

} 

// Return an end-of-paragraph if no more text source, 
return new TextEndOfParagraph(l); 



' Used by the TextFormatter object to retrieve a run of text from the text source. 

Public Overrides Function GetTextRun(ByVal textSourceCharacterIndex As Integer) As TextRun 
' Make sure text source index is in bounds. 

If textSourceCharacterIndex < 0 Then 

Throw New ArgumentOutOfRangeException("textSourceCharacterIndex"j "Value must be greater than 0.") 

End If 

If textSourceCharacterIndex >= _text.Length Then 
Return New TextEndOfParagraph(l) 

End If 

' Create TextCharacters using the current font rendering properties. 

If textSourceCharacterIndex < _text.Length Then 

Return New TextCharacters(_textj textSourceCharacterIndex, _text.Length - textSourceCharacterIndex, New 
GenericTextRunProperties(_currentRendering)) 

End If 

' Return an end-of-paragraph if no more text source. 

Return New TextEndOfParagraph(l) 

End Function 


NOTE 

In this example, the text store provides the same text properties to all of the text. Advanced text stores would need to 
implement their own span management to allow individual characters to have different properties. 


Specifying Formatting Properties 

TextRun objects are formatted by using properties provided by the text store. These properties come in two types, 
TextParagraphProperties and TextRunProperties. TextParagraphProperties handle paragraph inclusive properties 
such as TextAlignment and FlowDirection. TextRunProperties are properties that can be different for each text run 
within a paragraph, such as foreground brush. Typeface, and font size. To implement custom paragraph and 
custom text run property types, your application must create classes that derive from TextParagraphProperties and 
TextRunProperties respectively. 

See also 

• Typography in WPF 

• Documents in WPF 
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Windows Presentation Foundation (WPF) includes support for rich presentation of text using OpenType fonts. A 
sample pack of OpenType fonts is included with the Windows SDK. 

In This Section 

OpenType Font Features 
Packaging Fonts with Applications 
Sample OpenType Font Pack 
How-to Topics 

See also 

• FontStyle 

• SystemFonts 

• Documents in WPF 

• Typography in WPF 




OpenType Font Features 
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This topic provides an overview of some of the key features of OpenType font technology in Windows 
Presentation Foundation (WPF). 

OpenType Font Format 

The OpenType font format is an extension of the TrueType® font format, adding support for PostScript font data. 
The OpenType font format was developed jointly by Microsoft and Adobe Corporation. OpenType fonts and the 
operating system services which support OpenType fonts provide users with a simple way to install and use fonts, 
whether the fonts contain TrueType outlines or CFF (PostScript) outlines. 

The OpenType font format addresses the following developer challenges: 

• Broader multi-platform support. 

• Better support for international character sets. 

• Better protection for font data. 

• Smaller file sizes to make font distribution more efficient. 

• Broader support for advanced typographic control. 


NOTE 

The Windows SDK contains a set of sample OpenType fonts that you can use with Windows Presentation Foundation (WPF) 
applications. These fonts provide most of the features illustrated in the rest of this topic. For more information, see Sample 
OpenType Font Pack. 


For details of the OpenType font format, see the OpenType specification. 

Advanced Typographic Extensions 

The Advanced Typographic tables (OpenType Layout tables) extend the functionality of fonts with either TrueType 
or CFF outlines. OpenType Layout fonts contain additional information that extends the capabilities of the fonts to 
support high-quality international typography. Most OpenType fonts expose only a subset of the total OpenType 
features available. OpenType fonts provide the following features. 

• Rich mapping between characters and glyphs that support ligatures, positional forms, alternates, and other 
font substitutions. 

• Support for two-dimensional positioning and glyph attachment. 

• Explicit script and language information contained in font, so a text-processing application can adjust its 
behavior accordingly. 

The OpenType Layout tables are described in more detail in the "Font File Tables" section of the OpenType 
specification. 

The remainder of this overview introduces the breadth and flexibility of some of the visually-interesting OpenType 
features that are exposed by the properties of the Typography object For more information on this object see 
Typography Class. 





Variants 

Variants are used to render different typographic styles, such as superscripts and subscripts. 

Superscripts and Subscripts 

The Variants property allows you to set superscript and subscript values for an OpenType font. 

The following text displays superscripts for the Palatino Linotype font. 

23 14 th 

The following markup example shows how to define superscripts for the Palatino Linotype font, using properties 
of the Typography object. 

<Paragraph FontFamily="Palatino Linotype"> 

2<Run Typography .Variants="Superscr'ipt">3</Run> 

14<Run Typography.Variants="Superscript">th</Run> 

</Paragraph> 


The following text displays subscripts for the Palatino Linotype font. 

H 2 O Footnote4 

The following markup example shows how to define subscripts for the Palatino Linotype font, using properties of 
the Typography object. 

<Paragraph FontFamily="Palatino Linotype"> 

H<Run Typography.Variants="Subscript">2</Run>0 
FootnotecRun Typography.Variants="Subscript">4</Run> 

</Paragraph> 


Decorative Uses of Superscripts and Subscripts 

You can also use superscripts and subscripts to create decorative effects of mixed case text. The following text 
displays superscript and subscript text for the Palatino Linotype font. Note that the capitals are not affected. 

(^hapter Qne 


Chapter O 


ne 


The following markup example shows how to define superscripts and subscripts for a font, using properties of the 
Typography object. 


cParagraph FontFamily="Palatino Linotype" Typography.Variants="Superscript"> 
Chapter One 
</Paragraph> 

cParagraph FontFamlly="Palatino Linotype" Typography.Variants="Subscript"> 
Chapter One 
</Paragraph> 


Capitals 

Capitals are a set of typographical forms that render text in capital-styled glyphs. Typically, when text is rendered 
as all capitals, the spacing between letters can appear too tight, and the weight and proportion of the letters too 




heavy. OpenType supports a number of styling formats for capitals, including small capitals, petite capitals, titling, 
and capital spacing. These styling formats allow you to control the appearance of capitals. 


The following text displays standard capital letters for the Pescadero font, followed by the letters styled as 
"SmallCaps" and "AllSmallCaps". In this case, the same font size is used for all three words. 

CAPITALS Capitals capitals 


The following markup example shows how to define capitals for the Pescadero font, using properties of the 
Typography object. When the "SmallCaps" format is used, any leading capital letter is ignored. 

<Paragraph FontFamily="Pescadero" FontSize="48"> 

<Run>CAPITALS</Run> 

<Run Typography.Capitals="SmallCaps">Capitals</Run> 

<Run Typography.Capitals="AllSmallCaps">Capitals</Run> 

</Paragraph> 


Titling Capitals 

Titling capitals are lighter in weight and proportion and designed to give a more elegant look than normal 
capitals. Titling capitals are typically used in larger font sizes as headings. The following text displays normal and 
titling capitals for the Pescadero font. Notice the narrower stem widths of the text on the second line. 


CHAPTER ONE 
CHAPTER ONE 


The following markup example shows how to define titling capitals for the Pescadero font, using properties of the 
Typography object. 

<Paragraph FontFamily="Pescadero"> 

<Run Typography.Capitals="Titling">chapter one</Run> 

</Paragraph> 


Capital Spacing 

Capital spacing is a feature that allows you to provide more spacing when using all capitals in text. Capital letters 
are typically designed to blend with lowercase letters. Spacing that appears attractive between and a capital letter 
and a lowercase letter may look too tight when all capital letters are used. The following text displays normal and 
capital spacing for the Pescadero font. 

CHAPTER ONE 
CHAPTER ONE 


The following markup example shows how to define capital spacing for the Pescadero font, using properties of 
the Typography object. 

<Paragraph FontFamily="Pescadero"> 

<Run Typography.CapitalSpacing="True">CHAPTER ONE</Run> 

</Paragraph> 




Ligatures 

Ligatures are two or more glyphs that are formed into a single glyph in order to create more readable or 
attractive text. OpenType fonts support four types of ligatures: 

• Standard ligatures. Designed to enhance readability. Standard ligatures include "fi", "fl", and "ff". 

• Contextual ligatures. Designed to enhance readability by providing better joining behavior between the 
characters that make up the ligature. 

• Discretionary ligatures. Designed to be ornamental, and not specifically designed for readability. 

• Historical ligatures. Designed to be historical, and not specifically designed for readability. 

The following text displays standard ligature glyphs for the Pericles font. 

FI FL TH TTTVTW TY Vr WT YT 


The following markup example shows how to define standard ligature glyphs for the Pericles font, using 
properties of the Typography object. 

<Paragraph FontFamily="Pericles" Typography.StandardLigatures="True"> 

<Run Typography.StylisticAlternates="l">FI</Run> 

<Run Typography.StylisticAlternates="l">FL</Run> 

<Run Typography.StyllsticAlternates="l">TFI</Run> 

<Run Typography.StylisticAlternates="l">TT</Run> 

<Run Typography.StylisticAlternates="l">TV</Run> 

<Run Typography.StylisticAlternates="l">TW</Run> 

<Run Typography.StylisticAlternates="l">TY</Run> 

<Run Typography.StylisticAlternates="l">VT</Run> 

<Run Typography.StylisticAlternates="l">WT</Run> 

<Run Typography.StylisticAlternates="l">YT</Run> 

</Paragraph> 


The following text displays discretionary ligature glyphs for the Pericles font. 

(o lA LE U LL LO LU 

The following markup example shows how to define discretionary ligature glyphs for the Pericles font, using 
properties of the Typography object. 

<Paragraph FontFamily="Pericles" Typography.DiscretionaryLigatures="True"> 

<Run Typography.StylisticAlternates="l">CO</Run> 

<Run Typography.StylisticAlternates="l">LA</Run> 

<Run Typography.StylisticAlternates="l">LE</Run> 

<Run Typography.StylisticAlternates="l">LI</Run> 

<Run Typography.StylisticAlternates="l">LL</Run> 

<Run Typography.StylisticAlternates="l">LO</Run> 

<Run Typography.StylisticAlternates="l">LU</Run> 

</Paragraph> 


By default, OpenType fonts in Windows Presentation Foundation (WPF) enable standard ligatures. For example, if 
you use the Palatino Linotype font, the standard ligatures "fi", "ff", and "fl" appear as a combined character glyph. 
Notice that the pair of characters for each standard ligature touch each other. 


fifffl 



However, you can disable standard ligature features so that a standard ligature such as "ff" displays as two 
separate glyphs, rather than as a combined character glyph. 


f i f f f 1 

The following markup example shows how to disable standard ligature glyphs for the Palatino Linotype font, 
using properties of the Typography object. 

<!-- Set standard ligatures to false in order to disable feature. --> 

<Paragraph Typography.StandardLigatures="False" FontFamily="Palatino Linotype" FontSize="72"> 
fi ff fl 
</Paragraph> 


Swashes 

Swashes are decorative glyphs that use elaborate ornamentation often associated with calligraphy. The following 
text displays standard and swash glyphs for the Pescadero font. 

ABCDEFGHIJKLMN 

A'3 

Swashes are often used as decorative elements in short phrases such as event announcements. The following text 
uses swashes to emphasize the capital letters of the name of the event. 


Wishing you a 

'li ap py TM e w\ear! 

The following markup example shows how to define swashes for a font, using properties of the Typography 
object. 

<Paragraph FontFamily="Pescadero" TextBlock.TextAlignment="Center"> 

Wishing you a<LineBreak/> 

<Run Typography.StandardSwashes="l" FontSize="36">Happy New Year!</Run> 

</Paragraph> 


Contextual Swashes 

Certain combinations of swash glyphs can cause an unattractive appearance, such as overlapping descenders on 
adjacent letters. Using a contextual swash allows you to use a substitute swash glyph that produces a better 
appearance. The following text shows the same word before and after a contextual swash is applied. 

‘lyon ‘Xyon 

The following markup example shows how to define a contextual swash for the Pescadero font, using properties 
of the Typography object. 

<Paragraph FontFamily="Pescadero" Typography.StandardSwashes="l"> 

Lyon <Run Typography.ContextualSwashes="l">L</Run>yon 
</Paragraph> 




Alternates 


Alternates are glyphs that can be substituted for a standard glyph. OpenType fonts, such as the Pericles font used 
in the following examples, can contain alternate glyphs that you can use to create different appearances for text. 
The following text displays standard glyphs for the Pericles font. 


ANCIENT CREEK MYTHOLOGY 


The Pericles OpenType font contains additional glyphs that provide stylistic alternates to the standard set of 
glyphs. The following text displays stylistic alternate glyphs. 


ANCIENT GRUK MYTHOLOGY 


The following markup example shows how to define stylistic alternate glyphs for the Pericles font, using 
properties of the Typography object. 

<Paragraph FontFamily="Pericles"> 

<Run Typography.StyllsticAlternates="l">A</Run>NCIENT 
GR<Run Typography.StylisticAlternates="l">EE</Run>K 
MYTH<Run Typography.StylisticAlternates="l">0</Run>LOGY 
</Paragraph> 


The following text displays several other stylistic alternate glyphs for the Pericles font. 

AAAC^COQRR$Y 


The following markup example shows how to define these other stylistic alternate glyphs. 


<Paragraph FontFamily="Pericles"> 

<Run Typography.StylisticAlternates=" 

1">A</Run> 

<Run Typography.StylisticAlternates=" 

2">A</Run> 

<Run Typography.StylisticAlternates=" 

3">A</Run> 

<Run Typography.StylisticAlternates=" 

l">C</Run> 

<Run Typography.StylisticAlternates=" 

1">E</Run> 

<Run Typography.StylisticAlternates=" 

1">G</Run> 

<Run Typography.StylisticAlternates=" 

1">0</Run> 

<Run Typography.StylisticAlternates=" 

1">Q</Run> 

<Run Typography.StylisticAlternates=" 

1">R</Run> 

<Run Typography.StylisticAlternates=" 

2">R</Run> 

<Run Typography.StylisticAlternates=" 

l">S</Run> 

<Run Typography.StylisticAlternates=" 

1">Y</Run> 

</Paragraph> 



Random Contextual Alternates 

Random contextual alternates provide multiple substitute glyphs for a single character. When implemented with 
script-type fonts, this feature can simulate handwriting by using of a set of randomly chosen glyphs with slight 
differences in appearance. The following text uses random contextual alternates for the Lindsey font. Notice that 
the letter "a" varies slightly in appearance 

iv) ^ 


The following markup example shows how to define random contextual alternates for the Lindsey font, using 
properties of the Typography object. 




<TextBlock FontFamily="Lindsey"> 

<Run Typography .Context ualAlter'nates="True"> 
a banana in a cabana 
</Run> 

</TextBlock> 


Historical Forms 

Historical forms are typographic conventions that were common in the past. The following text displays the 
phrase, "Boston, Massachusetts", using an historical form of glyphs for the Palatino Linotype font. 

Bofton, Maffachufettf 

The following markup example shows how to define historical forms for the Palatino Linotype font, using 
properties of the Typography object. 

<Paragraph FontFamily="Palatino Linotype"> 

<Run Typography.HistoricalForms="True">Bostonj Massachusetts</Run> 

</Paragraph> 


Numerical Styles 

OpenType fonts support a large number of features that can be used with numerical values in text. 

Fractions 

OpenType fonts support styles for fractions, including slashed and stacked. 

The following text displays fraction styles for the Palatino Linotype font. 

Vs V4 Vs V2 % % % 

11111 37 

8 4 8 2 8 4 8 

The following markup example shows how to define fraction styles for the Palatino Linotype font, using properties 
of the Typography object. 

<Paragraph FontFamily="Palatino Linotype" Typography.Fraction="Slashed"> 

1/8 1/4 3/8 1/2 5/8 3/4 7/8 
</Paragraph> 

<Paragraph FontFamily="Palatino Linotype" Typography.Fraction="Stacked"> 

1/8 1/4 3/8 1/2 5/8 3/4 7/8 
</Paragraph> 

Old Style Numerals 

OpenType fonts support an old style numeral format. This format is useful for displaying numerals in styles that 
are no longer standard. The following text displays an 18th century date in standard and old style numeral 
formats for the Palatino Linotype font. 

July 4,1776 July 4,1776 

The following text displays standard numerals for the Palatino Linotype font, followed by old style numerals. 

1234567890 1234567890 





The following nnarkup example shows how to define old style numerals for the Palatino Linotype font, using 
properties of the Typography object. 

<Paragraph FontFamily="Palatino Linotype"> 

<Run Typography.NumeralStyle="Mormal">1234567890</Run> 

<Run Typography.NumeralStyle="01dStyle">1234567890</Run> 

</Paragraph> 


Proportional and Tabular Figures 

OpenType fonts support a proportional and tabular figure feature to control the alignment of widths when using 
numerals. Proportional figures treat each numeral as having a different width—"1" is narrower than "5". Tabular 
figures are treated as equal-width numerals so that they align vertically, which increases the readability of 
financial type information. 

The following text displays two proportional figures in the first column using the Miramonte font. Note the 
difference in width between the numerals "5" and "1". The second column shows the same two numeric values 
with the widths adjusted by using the tabular figure feature. 

550,689 550,689 

114,131 114,131 


The following markup example shows how to define proportional and tabular figures for the Miramonte font, 
using properties of the Typography object. 

<TextBlock FontFamily="Miramonte"> 

<Run Typography.NumeralAlignment="Proportional">114,131</Run> 

</TextBlock> 

<TextBlock FontFamily="Miramonte"> 

<Run Typography.NumeralAlignment="Tabular">114,131</Run> 

</TextBlock> 


Slashed Zero 

OpenType fonts support a slashed zero numeral format to emphasize the difference between the letter "O" and 
the numeral "0". The slashed zero numeral is often used for identifiers in financial and business information. 

The following text displays a sample order identifier using the Miramonte font. The first line uses standard 
numerals. The second line used slashed zero numerals to provide better contrast with the uppercase "O" letter. 

Order #0048-OTC-390 
Order #0048-OTC-390 


The following markup example shows how to define slashed zero numerals for the Miramonte font, using 
properties of the Typography object. 

<Paragraph FontFamily="Miramonte"> 

<Run>0rder #0048-OTC-390</Run> 

<LineBreak/> 

<Run Typography.SlashedZero="True">Order #0048-OTC-390</Run> 

</Paragraph> 


Typography Class 



The Typography object exposes the set of features that an OpenType font supports. By setting the properties of 
Typography in markup, you can easily author documents that take advantage of OpenType features. 


The following text displays standard capital letters for the Pescadero font, followed by the letters styled as 
"SmallCaps" and "AllSmallCaps". In this case, the same font size is used for all three words. 

CAPITALS Capitals capitals 


The following markup example shows how to define capitals for the Pescadero font, using properties of the 
Typography object. When the "SmallCaps" format is used, any leading capital letter is ignored. 

<Paragr'aph FontFamily="Pescader'o" FontSize="48"> 

<Run>CAPITALS</Run> 

<Run Typography.Capitals="SmallCaps">Capitals</Run> 

<Run Typography.Capitals="AllSmallCaps">Capitals</Run> 

</Paragraph> 


The following code example accomplishes the same task as the previous markup example. 

MyParagraph.FontFamily = new FontFamilyC'Pescadero"); 

MyParagraph.FontSize = 48; 

Run run_l = new Run("CAPITALS "); 

MyParagraph.Inlines.Add(run_l); 

Run run_2 = new Run("Capitals "); 

run_2.Typography.Capitals = FontCapitals.SmallCaps; 

MyParagraph.Inlines.Add(run_2); 

Run run_3 = new Run("Capitals"); 

run_3.Typography.Capitals = FontCapitals.AllSmallCaps; 

MyParagraph.Inlines.Add(run_3); 

MyParagraph.Inlines.Add(new LineBreak()); 


MyParagraph.FontFamily = New FontFamilyC'Pescadero") 
MyParagraph.FontSize = 48 

Dim run_l As New Run("CAPITALS ") 

MyParagraph.Inlines.Add(run_l) 

Dim run_2 As New Run("Capitals ") 

run_2.Typography.Capitals = FontCapitals.SmallCaps 

MyParagraph.Inlines.Add(run_2) 

Dim run_3 As New Run("Capitals") 

run_3.Typography.Capitals = FontCapitals.AllSmallCaps 
MyParagraph.Inlines.Add(run_3) 

MyParagraph.Inlines.Add(New LineBreak()) 


Typography Class Properties 

The following table lists the properties, values, and default settings of the Typography object. 


PROPERTY 

VALUE(S) 

DEFAULT VALUE 

AnnotationAlternates 

Numeric value - byte 

0 




PROPERTY 


VALUE(S) 


DEFAULT VALUE 


Capitals 

AllPetiteCaps | AllSmallCaps | Normal | 
PetiteCaps | SmallCaps | Titling | Unicase 

FontCapitals.Normal 

Capitalspacing 

Boolean 


false 

CaseSensitiveForms 

Boolean 


false 

ContextualAlternates 

Boolean 


true 

ContextualLigatures 

Boolean 


true 

ContextualSwashes 

Numeric value - 

byte 

0 

DiscretionaryLigatures 

Boolean 


false 

EastAsianExpertForms 

Boolean 


false 

EastAsianLanguage 

HojoKanji | Jis04 | Jis78 | Jis83 | Jis90 | 
NIcKanji | Normal | Simplified | 

Traditional | TraditionalNames 

FontEastAsianLanguage.Normal 

EastAsianWidths 

Full 1 Half 1 Normal | Proportional | 

Quarter | Third 

FontEastAsianWidths.Normal 

Fraction 

Normal | Slashec 

1 1 Stacked 

FontFraction.Normal 

HistoricalForms 

Boolean 


false 

HistoricalLigatures 

Boolean 


false 

Kerning 

Boolean 


true 

MathematicalGreek 

Boolean 


false 

NumeralAlignment 

Normal | Proportional | Tabular 

FontNumeralAlignment.Normal 

NumeralStyle 

Boolean 


FontNumeralStyle.Normal 

SlashedZero 

Boolean 


false 

StandardLigatures 

Boolean 


true 

StandardSwashes 

numeric value - 

byte 

0 

StylisticAlternates 

numeric value - 

byte 

0 

StylisticSetl 

Boolean 


false 

StylisticSetZ 

Boolean 


false 
















PROPERTY 


VALUE(S) 


DEFAULT VALUE 


StylisticSetS 

Boolean 

false 

StylisticSet4 

Boolean 

false 

StylisticSetS 

Boolean 

false 

StylisticSet6 

Boolean 

false 

StylisticSet? 

Boolean 

false 

StylisticSetS 

Boolean 

false 

StylisticSet9 

Boolean 

false 

StylisticSetIO 

Boolean 

false 

StylisticSetl 1 

Boolean 

false 

StylisticSet12 

Boolean 

false 

StylisticSetl 3 

Boolean 

false 

StylisticSetl 4 

Boolean 

false 

StylisticSetl 5 

Boolean 

false 

StylisticSetl 6 

Boolean 

false 

StylisticSetl? 

Boolean 

false 

StylisticSetl 8 

Boolean 

false 

StylisticSetl 9 

Boolean 

false 

StylisticSetZO 

Boolean 

false 

Variants 

Inferior | Normal | Ordinal | Ruby | 
Subscript 1 Superscript 

FontVariants.Normal 


See also 

• Typography 

• OpenType specification 

• Typography in WPF 

• Sample OpenType Font Pack 

• Packaging Fonts with Applications 
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This topic provides an overview of how to package fonts with your Windows Presentation Foundation (WPF) 
application. 


NOTE 

As with most types of software, font files are licensed, rather than sold. Licenses that govern the use of fonts vary from 
vendor to vendor but in general most licenses, including those covering the fonts Microsoft supplies with applications and 
Windows, do not allow the fonts to be embedded within applications or otherwise redistributed. Therefore, as a developer it 
is your responsibility to ensure that you have the required license rights for any font you embed within an application or 
otherwise redistribute. 


Introduction to Packaging Fonts 

You can easily package fonts as resources within your WPF applications to display user interface text and other 
types of text based content. The fonts can be separate from or embedded within the application's assembly files. 
You can also create a resource-only font library, which your application can reference. 

OpenType and TrueType® fonts contain a type flag, fsType, that indicates font embedding licensing rights for the 
font. However, this type flag only refers to embedded fonts stored in a document-it does not refer to fonts 
embedded in an application. You can retrieve the font embedding rights for a font by creating a GlyphTypeface 
object and referencing its EmbeddingRights property. Refer to the "OS/2 and Windows Metrics" section of the 
OpenType Specification for more information on the fsType flag. 

The Microsoft Typography Web site includes contact information that can help you locate a particular font vendor 
or find a font vendor for custom work. 

Adding Fonts as Content Items 

You can add fonts to your application as project content items that are separate from the application's assembly 
files. This means that content items are not embedded as resources within an assembly. The following project file 
example shows how to define content items. 

<Project DefaultTargets="Build" 

xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 

<!-- Other project build settings ... --> 

<ItemGroup> 

<Content Include="Peric.ttf" /> 

<Content Include="Pericl.ttf" /> 

</ItemGroup> 

</Project> 


In order to ensure that the application can use the fonts at run time, the fonts must be accessible in the 
application's deployment directory. The <copyToOutputDirectory> element in the application's project file allows 
you to automatically copy the fonts to the application deployment directory during the build process. The 
following project file example shows how to copy fonts to the deployment directory. 







<ItemGroup> 

<Content Include="Peric.ttf"> 

<CopyToOutputDir'ectory>PreserveNewest</CopyToOutputDirectory> 

</Content> 

<Content Include="Pericl.ttf"> 

<CopyToOutputDir'ectory>PreservelMewest</CopyToOutputDirectory> 

</Content> 

</ItemGr'oup> 


The following code example shows how to reference the application's font as a content item—the referenced 
content item must be in the same directory as the application's assembly files. 

<TextBlock FontFamily="./#Pericles Light"> 

Aegean Sea 
</TextBlock> 


Adding Fonts as Resource Items 

You can add fonts to your application as project resource items that are embedded within the application's 
assembly files. Using a separate subdirectory for resources helps to organize the application's project files. The 
following project file example shows how to define fonts as resource items in a separate subdirectory. 

<Project DefaultTargets="Build" 

xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> 

<!-- Other project build settings ... --> 

<ItemGroup> 

<Resource Include="resources\Peric.ttf" /> 

<Resource Include="resources\Pericl.ttf" /> 

</ItemGroup> 

</Project> 


NOTE 

When you add fonts as resources to your application, make sure you are setting the <Resource> element, and not the 
<EmbeddedResource> element in your application's project file. The <EmbeddedResource> element for the build action is 
not supported. 


The following markup example shows how to reference the application's font resources. 

<TextBlock FontFamily="./resources/#Pericles Light"> 

Aegean Sea 
</TextBlock> 


Referencing Font Resource Items from Code 

In order to reference font resource items from code, you must supply a two-part font resource reference: the base 
uniform resource identifier (URI); and the font location reference. These values are used as the parameters for the 
FontFamily method. The following code example shows how to reference the application's font resources in the 
project subdirectory called resources . 

// The font resource reference includes the base URI reference (application directory level)j 
// and a relative URI reference. 

myTextBlock.FontFamily = new FontFamily(new Uri("pack://application:j „/")j "./resources/#Pericles Light"); 







' The font resource reference includes the base URI reference (application directory level), 

' and a relative URI reference. 

myTextBlock.FontFamily = New FontFamily(New Uri("pack://application:./resources/#Pericles Light") 


The base uniform resource identifier (URI) can include the application subdirectory where the font resource 
resides. In this case, the font location reference would not need to specify a directory, but would have to include a 
leading " ./ ", which indicates the font resource is in the same directory specified by the base uniform resource 
identifier (URI). The following code example shows an alternate way of referencing the font resource item—it is 
equivalent to the previous code example. 

// The base URI reference can include an application subdirectory. 

myTextBlock.FontFamily = new FontFamily(new Uri("pack://application:,,,/resources/"), "./#Pericles Light"); 


' The base URI reference can include an application subdirectory. 

myTextBlock.FontFamily = New FontFamily(New Uri("pack://application:,,,/resources/"), "./#Pericles Light") 


Referencing Fonts from the Same Application Subdirectory 

You can place both application content and resource files within the same user-defined subdirectory of your 
application project. The following project file example shows a content page and font resources defined in the 
same subdirectory. 

<ItemGroup> 

<Page Include="pages\FlomePage.xaml" /> 

</ItemGroup> 

<ItemGroup> 

<Resource Include="pages\Peric.ttf" /> 

<Resource Include="pages\Pericl.ttf" /> 

</ItemGroup> 


Since the application content and font are in the same subdirectory, the font reference is relative to the application 
content. The following examples show how to reference the application's font resource when the font is in the 
same directory as the application. 

<TextBlock FontFamily="./#Pericles Light"> 

Aegean Sea 
</TextBlock> 


// The font resource reference includes the base Uri (application directory level), 

// and the file resource location, which is relative to the base Uri. 

myTextBlock.FontFamily = new FontFamily(new Uri("pack://application:,,,/"), "/pages/#Pericles Light"); 


' The font resource reference includes the base Uri (application directory level), 

' and the file resource location, which is relative to the base Uri. 

myTextBlock.FontFamily = New FontFamily(New Uri("pack://application:,,,/"), "/pages/#Pericles Light") 


Enumerating Fonts in an Application 

To enumerate fonts as resource items in your application, use either the GetFontFamilies or GetTypefaces method. 
The following example shows how to use the GetFontFamilies method to return the collection of FontFamily 
objects from the application font location. In this case, the application contains a subdirectory named "resources". 







foreach (FontFamily fontFamily in Fonts.GetFontFamilies(new Uri("pack://application:j,j/")j "./resources/")) 

{ 

// Perform action. 

} 


For Each fontFamily As FontFamily In Fonts.GetFontFamilies(New Llri("pack://application:, j,/"), "./resources/") 
' Perform action. 

Next fontFamily 


The following example shows how to use the GetTypefaces method to return the collection of Typeface objects 
from the application font location. In this case, the application contains a subdirectory named "resources". 

foreach (Typeface typeface in Fonts.GetTypefaces(new Llri("pack://application:„,/"), "./resources/")) 

{ 

// Perform action. 

} 


For Each typeface As Typeface In Fonts.GetTypefaces(New Uri("pack://application: j„/")j "./resources/") 
' Perform action. 

Next typeface 


Creating a Font Resource Library 

You can create a resource-only library that contains only fonts—no code is part of this type of library project. 
Creating a resource-only library is a common technique for decoupling resources from the application code that 
uses them. This also allows the library assembly to be included with multiple application projects. The following 
project file example shows the key portions of a resource-only library project. 

<PropertyGroup> 

<AssemblyNamexFontLibrany</AssemblyName> 

<OutputType>library</OutputType> 

</PropertyGroup> 

<ItemGroup> 

cResource Include="Kooten.ttf" /> 
cResource Include="Pesca.ttf" /> 

</ItemGroup 


Referencing a Font in a Resource Library 

To reference a font in a resource library from your application, you must prefix the font reference with the name of 
the library assembly. In this case, the font resource assembly is "FontLibrary". To separate the assembly name from 
the reference within the assembly, use a character. Adding the "Component" keyword followed by the reference 
to the font name completes the full reference to the font library's resource. The following code example shows 
how to reference a font in a resource library assembly. 

<Run FontFamily="/FontLibranyiComponent/ttKootenay" FontSize="36"> 

ABCDE FGHIIKLMNOPQRSTUVWXYZ 
</Run> 






NOTE 

This SDK contains a set of sampie OpenType fonts that you can use with WPF appiications. The fonts are defined in a 
resource-oniy iibrary. For more information, see Sampie OpenType Font Pack. 


Limitations on Font Usage 

The foiiowing list describes several limitations on the packaging and use of fonts in WPF applications: 

• Font embedding permission bits: WPF applications do not check or enforce any font embedding 
permission bits. See the lntroduction_to_Packing Fonts section for more information. 

• Site of origin fonts: WPF applications do not allow a font reference to an http or ftp uniform resource 
identifier (URI). 

• Absolute URI using the pack: notation: WPF applications do not allow you to create a FontFamily 
object programmatically using "pack:" as part of the absolute uniform resource identifier (URI) reference to 
a font. For example, "pack://appiication:,„/resources/#Pericies Light" is an invalid font reference. 

• Automatic font embedding: During design time, there is no support for searching an application's use of 
fonts and automatically embedding the fonts in the application's resources. 

• Font subsets: WPF applications do not support the creation of font subsets for non-fixed documents. 

• In cases where there is an incorrect reference, the application falls back to using an available font. 

See also 

• Typography 

• FontFamily 

• Microsoft Typography: Links, News, and Contacts 

• OpenType Specification 

• OpenType Font Features 

• Sample OpenType Font Pack 




Sample OpenType Font Pack 
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This topic provides an overview of the sample OpenType fonts that are distributed with the Windows SDK. The 
sample fonts support extended OpenType features that can be used by Windows Presentation Foundation (WPF) 
applications. 

Fonts in the OpenType Font Pack 

The Windows SDK provides a set of sample OpenType fonts that you can use in creating Windows Presentation 
Foundation (WPF) applications. The sample fonts are supplied under license from Ascender Corporation. These 
fonts implement only a subset of the total features defined by the OpenType format. The following table lists the 
names of the sample OpenType fonts. 


NAME 

FILE 

Kootenay 

Kooten.ttf 

Lindsey 

Linds.ttf 

Miramonte 

Miramo.ttf 

Miramonte Bold 

Miramob.ttf 

Pericles 

Peric.ttf 

Pericles Light 

Pericl.ttf 

Pescadero 

Pesca.ttf 

Pescadero Bold 

Pescab.ttf 


The following illustration shows what the sample OpenType fonts look like. 

Kootenay 

Lii1^ls6C( 

M iramonte 

Miramonte Bold 

Pericles 

Pericles Light 

Pescadero 

Pescadero Bold 




The sample fonts are supplied under license from Ascender Corporation. Ascender is a provider of advanced font 
products. To license extended or custom versions of the sample fonts, see Ascender Corporation's Web site. 


NOTE 

As a developer it is your responsibility to ensure that you have the required license rights for any font you embed within an 
application or otherwise redistribute. 


Installing the Fonts 

You have the option of installing the sample OpenType fonts to the default Windows Fonts directory, 
\WINDOWS\Fonts. Use the Fonts control panel to install the fonts. Once these fonts are on your computer, they 
are accessible to all applications that reference default Windows fonts. You can display a representative set of 
characters in several font sizes by doubling-clicking the font file. The following screenshot shows the Lindsey font 
file, Linds.ttf. 



Displaying the Lindsey font 

Using the Fonts 

There are two ways that you can use fonts in your application. You can add fonts to your application as project 
content items that are not embedded as resources within an assembly. Alternatively, you can add fonts to your 
application as project resource items that are embedded within the application's assembly files. For more 
information, see Packaging Fonts with Applications. 

See also 

• Typography 

• OpenType Font Features 

• Packaging Fonts with Applications 
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The topics in this section demonstrate how to use the font features included with Windows Presentation 
Foundation (WPF). 

In This Section 

Enumerate System Fonts 
Use the FontSizeConverter Class 

See also 

• FontStyle 

• SystemFonts 

• Documents in WPF 

• Typography in WPF 




How to: Enumerate System Fonts 
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Example 

The following example shows how to enumerate the fonts in the system font collection. The font family name of 
each FontFamily within SystemFontFamilies is added as an item to a combo box. 

public void FillFontComboBox(ComboBox comboBoxFonts) 

{ 

// Enumerate the current set of system fontSj 

// and fill the combo box with the names of the fonts. 

foreach (FontFamily fontFamily in Fonts.SystemFontFamilies) 

{ 

// FontFamily.Source contains the font family name. 
comboBoxFonts.Items.Add(fontFamily.Source); 

} 

comboBoxFonts.Selectedindex = 0; 

} 


Public Sub FillFontComboBox(By\/al comboBoxFonts As ComboBox) 

' Enumerate the current set of system fonts, 

' and fill the combo box with the names of the fonts. 

For Each fontFamily As FontFamily In Fonts.SystemFontFamilies 
' FontFamily.Source contains the font family name. 
comboBoxFonts.Items.Add(fontFamily.Source) 

Next fontFamily 

comboBoxFonts.Selectedindex = 0 
End Sub 


If multiple versions of the same font family reside in the same directory, the Windows Presentation Foundation 
(WPF) font enumeration returns the most recent version of the font. If the version information does not provide 
resolution, the font with latest timestamp is returned. If the timestamp information is equivalent, the font file that is 
first in alphabetical order is returned. 





How to: Use the FontSizeConverter Class 
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Example 

This example shows how to create an instance of FontSizeConverter and use it to change a font size. 

The example defines a custom method called changesize that converts the contents of a ListBoxItem, as defined in 
a separate Extensible Application Markup Language (XAML) file, to an instance of Double, and later into a String. 
This method passes the ListBoxItem to a FontSizeConverter object, which converts the Content of a ListBoxItem to 
an instance of Double. This value is then passed back as the value of the FontSize property of the TextBlock 
element. 

This example also defines a second custom method that is called changeFamiiy . This method converts the Content 
of the ListBoxItem to a String, and then passes that value to the FontFamily property of the TextBlock element. 

This example does not run. 

private void changeSize(object senderj SelectionChangedEventArgs args) 

{ 

ListBoxItem li = ((sender as ListBox).Selecteditem as ListBoxItem); 

FontSizeConverter myFontSizeConverter = new FontSizeConverter(); 

textl.FontSize = (Double)myFontSizeConverter.ConvertFromString(li.Content.ToString()); 

} 

private void changeFamily(object sender^ SelectionChangedEventArgs args) 

{ 

ListBoxItem liZ = ((sender as ListBox).Selecteditem as ListBoxItem); 

textl.FontFamily = new System.Windows.Media.FontFamily(li2.Content.ToString()); 

} 


See also 


• FontSizeConverter 







Glyphs 
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Glyphs are a low-level depiction of a character to be drawn on-screen. Windows Presentation Foundation (WPF) 
provides direct access to glyphs for customers who want to intercept and persist text after formatting. 

In This Section 

Introduction to the GlyphRun Object and Glyphs Element 
How to: Draw Text Using Glyphs 

See also 

• GlyphRun 

• DrawText 

• Glyphs 

• Documents in WPF 

• Typography in WPF 
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This topic describes the GlyphRun object and the Glyphs element. 

Introduction to GlyphRun 

Windows Presentation Foundation (WPF) provides advanced text support including glyph-level markup with direct 
access to Glyphs for customers who want to intercept and persist text after formatting. These features provide 
critical support for the different text rendering requirements in each of the following scenarios. 

1. Screen display of fixed-format documents. 

2. Print scenarios. 

• Extensible Application Markup Language (XAML) as a device printer language. 

• Microsoft XPS Document Writer. 

• Previous printer drivers, output from Win32 applications to the fixed format 

• Print spool format 

3. Fixed-format document representation, including clients for previous versions of Windows and other 
computing devices. 

NOTE 

Glyphs and GlyphRun are designed for fixed-format document presentation and print scenarios. Windows Presentation 
Foundation (WPF) provides several elements for general layout and user interface (Ul) scenarios such as Label and TextBlock. 

For more information on layout and Ul scenarios, see the Typography in WPF. 


The GlyphRun Object 

The GlyphRun object represents a sequence of glyphs from a single face of a single font at a single size, and with a 
single rendering style. 

GlyphRun includes both font details such as glyph Indices and individual glyph positions. It also includes the 
original Unicode code points the run was generated from, character-to-glyph buffer offset mapping information, 
and per-character and per-glyph flags. 

GlyphRun has a corresponding high-level FrameworkElement, Glyphs. Glyphs can be used in the element tree and 
in XAML markup to represent GlyphRun output 

The Glyphs Element 

The Glyphs element represents the output of a GlyphRun in XAML. The following markup syntax is used to describe 
the Glyphs element. 





<!-- The example shows how 
<Page 

' to use a Glyphs object. --> 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 

xmlns:x="http://schemas. 

> 

microsoft.com/winfx/2006/xaml" 

<StackPanel Background= 

"PowderBlue"> 

<Glyphs 


FontUri 

= "C:\WINDOWS\Fonts\TIMES.TTF" 

FontRenderingEmSize = "100" 

StyleSimulations 

= "BoldSimulation" 

UnicodeString 

= "Hello World!" 

Fill 

= "Black" 

OriginX 

= "100" 

OriginY 

= "200" 

/> 


</StackPanel> 


</Page> 



The following property definitions correspond to the first four attributes in the sample markup. 

PROPERTY DESCRIPTION 

FontUri Specifies a resource identifier: file name, Web uniform resource 

identifier (URI), or resource reference in the application .exe or 
container. 


FontRenderingEmSize Specifies the font size in drawing surface units (default is .96 

inches). 

StyleSimulations Specifies flags for bold and Italic styles. 

BidiLevel Specifies the bidirectional layout level. Even-numbered and 

zero values imply left-to-right layout; odd-numbered values 
imply right-to-left layout. 

Indices property 

The Indices property is a string of glyph specifications. Where a sequence of glyphs forms a single cluster, the 
specification of the first glyph in the cluster is preceded by a specification of how many glyphs and how many code 
points combine to form the cluster. The Indices property collects in one string the following properties. 

• Glyph indices 

• Glyph advance widths 

• Combining glyph attachment vectors 

• Cluster mapping from code points to glyphs 

• Glyph flags 

Each glyph specification has the following form. 

[GlyphIndex][j[Advance][^[uOffset][j[vOffset][j[Flags]]]]] 


Glyph Metrics 


Each glyph defines metrics that specify how it aligns with other Glyphs. The following graphic defines the various 




typographic qualities of two different glyph characters. 


H 


Left to right 
baseline origin 




Right to left 
baseline origin 


Upright baseline offset — 



Left side bearing 




Advance width 


Glyphs Markup 

The following code example shows how to use various properties of the Glyphs element in XAML. 


<!-- The example shows how to use different property settings of Glyphs objects. --> 
<Canvas 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

Bacl<ground="PowderBlue" 

> 


<Glyphs 

FontUri 

FontRenderingEmSize = 

StyleSimulations 

UnicodeString 

Fill 

OriginX 

OriginY 


"C:\WINDOWS\Fonts\ARIAL.TTF" 

"36" 

"ItalicSimulation" 

"Hello World I" 

"SteelBlue" 

"50" 

"75" 


<!-- "Hello World!" with default kerning --> 

<Glyphs 

FontUri = "C:\WINDOWS\Fonts\ARIAL.TTF" 

FontRenderingEmSize = "36" 

UnicodeString = "Hello World!" 

Fill = "Maroon" 


OriginX = "50" 

OriginY = "150" 


<!-- "Hello World!" with explicit character widths for proportional font 
<Glyphs 

FontUri = "C:\WINDOWS\Fonts\ARIAL.TTF" 

FontRenderingEmSize = "36" 

UnicodeString = "Hello World!" 

Indices = ", 80;,80;,80;,80;,80;j80;j80;j80;j80;j80;j80" 

Fill = "Maroon" 


OriginX = "50" 

OriginY = "225" 


--> 


<!-- "Hello World!" with fixed-width font --> 


w«l. 
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FontUri 

FontRenderingEmSize 

StyleSimulations 

UnicodeString 

Fill 

OriginX 

OriginY 


"C:\WINDOWS\Fonts\COUR.TTF" 

"36" 

"BoldSimulation" 

"Flello World!" 

"Maroon" 

"50" 

"300" 


<!-- "Open file" without 
<Glyphs 
FontUri 

FontRenderingEmSize = 

StyleSimulations 

UnicodeString 

Fill 


"fi" ligature --> 

"C:\WINDOWS\Fonts\TIMES.TTF" 

"36" 

"BoldSimulation" 

"Open file" 

"SlateGray" 


OriginX = "400" 

OriginY = "75" 


/> 


<!-- "Open file" with "fi" ligature --> 

<Glyphs 

FontUri = "C:\WINDOWS\Fonts\TIMES.TTF" 

FontRenderingEmSize = "36" 

StyleSimulations = "BoldSimulation" 

UnicodeString = "Open file" 

Indices = (2:1)191" 

Fill = "SlateGray" 


OriginX = "400" 

OriginY = "150" 


/> 


</Canvas> 


See also 

• Typography in WPF 

• Documents in WPF 

• Text 
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This topic explains how to use the low-level Glyphs object to display text in Extensible Application Markup 
Language (XAML). 

Example 

The following examples show how to define properties for a Glyphs object in Extensible Application Markup 
Language (XAML). The Glyphs object represents the output of a GlyphRun in XAML. The examples assume that the 
Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the local 
computer. 


<!-- The example shows how 
<Page 

' to use a Glyphs object. --> 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 

xmlns:x="http://schemas. 

> 

microsoft.com/winfx/2006/xaml" 

<StackPanel Background= 

"PowderBlue"> 

<Glyphs 


FontUri 

= "C:\WINDOWS\Fonts\TIMES.TTF" 

FontRenderingEmSize = "100" 

StyleSimulations 

= "BoldSimulation" 

UnicodeString 

= "Hello World!" 

Fill 

= "Black" 

OriginX 

= "100" 

OriginY 

= "200" 

/> 


</StackPanel> 


</Page> 



This example shows how to define other properties of Glyphs objects in XAML. 

<!-- The example shows how to use different property settings of Glyphs objects. --> 
<Canvas 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

Background="PowderBlue" 

> 

<Glyphs 
FontUri 

FontRenderingEmSize 
StyleSimulations 
UnicodeString 
Fill 
OriginX 
OriginY 

/> 

<!-- "Hello World!" with default kerning --> 

<Glyphs 

FontUri = "C:\WINDOWS\Fonts\ARIAL.TTF" 

FontRenderingEmSize = "36" 

UnicodeString = "Hello World!" 


= "C:\WINDOWS\Fonts\ARIAL.TTF" 
= "36" 

= "ItalicSimulation" 

= "Hello World!" 

= "SteelBlue" 

= "50" 

= "75" 





Fill 

OrlginX 

OriginY 


"Maroon" 

" 50 " 

"150" 


<!-- "Hello World!" with 
<Glyphs 
FontUri 

FontRenderingEmSize = 

UnicodeString 

Indices 


explicit character widths for proportional font 

"C:\WINDOWS\Fonts\ARIAL.TTF" 

"36" 

"Hello World!" 

"^ 80;^ 80;^ 80;^ 80;^ 80;j 80;j 80;j 80;j 80;j 80;j 80" 


Fill 


= "Maroon" 


OrlginX = "50" 

OriginY = "225" 


--> 


<!-- "Hello World!" with 
<Glyphs 

FontUri 

FontRenderingEmSize 
StyleSimulations 
UnicodeString 
Fill 


fixed-width font --> 

= "C:\WINDOWS\Fonts\COUR.TTF" 
= "36" 

= "BoldSimulation" 

= "Hello World!" 

= "Maroon" 


OriginX = "50" 

OriginY = "300" 


<!-- "Open file" without 
<Glyphs 
FontUri 

FontRenderingEmSize = 

StyleSimulations 

UnicodeString 

Fill 


"fi" ligature --> 

"C:\WINDOWS\Fonts\TIMES.TTF" 

"36" 

"BoldSimulation" 

"Open file" 

"SlateGray" 


OriginX = "400" 

OriginY = "75" 


/> 


<!-- "Open file" with "fi" ligature --> 
cGlyphs 

FontUri = "C:\WINDOWS\Fonts\TIMES.TTF" 

FontRenderingEmSize = "36" 

StyleSimulations = "BoldSimulation" 

UnicodeString = "Open file" 

Indices = ";;;;;(2:1)191" 

Fill = "SlateGray" 


OriginX = "400" 

OriginY = "150" 


/> 


</Canvas> 


See also 


• Typography in WPF 
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The topics in this section describe how to use Windows Presentation Foundation (WPF) support for rich 
presentation of text in your applications. 

In This Section 

Create a Text Decoration 

Specify Whether a Hyperlink is Underlined 

Apply Transforms to Text 

Apply Animations to Text 

Create Text with a Shadow 

Create Outlined Text 

Draw Text to a Control's Background 

Draw Text to a Visual 

Use Special Characters in XAML 

See also 

• Typography 

• Documents in WPF 

• OpenType Font Features 
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A TextDecoration object is a visual ornamentation you can add to text. There are four types of text decorations: 
underline, baseline, strikethrough, and overline. The following example shows the locations of the text decorations 
relative to the text. 


Overline 

StrikeThrough 
Underline 

To add a text decoration to text, create a TextDecoration object and modify its properties. Use the Location property 
to specify where the text decoration appears, such as underline. Use the Pen property to specify the appearance of 
the text decoration, such as a solid fill or gradient color. If you do not specify a value for the Pen property, the 
decorations defaults to the same color as the text. Once you have defined a TextDecoration object, add it to the 
TextDecorations collection of the desired text object. 

The following example shows a text decoration that has been styled with a linear gradient brush and a dashed pen. 

e m R h a_sLs 

The Hyperlink object is an inline-level flow content element that allows you to host hyperlinks within the flow 
content. By default. Hyperlink uses a TextDecoration object to display an underline. TextDecoration objects can be 
performance intensive to instantiate, particularly if you have many Hyperlink objects. If you make extensive use of 
Hyperlink elements, you may want to consider showing an underline only when triggering an event, such as the 
MouseEnter event. 

In the following example, the underline for the "My MSN" link is dynamic—it only appears when the MouseEnter 
event is triggered. 


r^TWEsr 






MSN Home 1 Mv MSN 



MSN Home 1 M^MSN 



For more information, see Specify Whether a Hyperlink is Underlined. 

Example 

In the following code example, an underline text decoration uses the default font value. 

// Use the default font values for the strikethrough text decoration, 
private void SetDefaultStrikethrough() 

{ 

// Set the underline decoration directly to the text block. 

TextBlockl.TextDecorations = TextDecorations.Strikethrough; 

} 






















' Use the default font values for the strikethrough text decoration. 
Private Sub SetDefaultStrikethrough() 

' Set the underline decoration directly to the text block. 
TextBlockl.TextDecorations = TextDecorations.Strikethrough 
End Sub 


<!-- Use the default font values for the strikethrough text decoration. --> 
<TextBlock 

TextDecorations="Strikethrough" 

FontSize="36" > 

The quick red fox 
</TextBlock> 


In the following code exannple, an underline text decoration is created with a solid color brush for the pen. 

// Use a Red pen for the underline text decoration, 
private void SetRedUnderline() 

{ 

// Create an underline text decoration. Default is underline. 

TextDecoration myUnderline = new TextDecoration()j 

// Create a solid color brush pen for the text decoration. 
myUnderline.Pen = new Pen(Brushes.Red^ 1 ); 

myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommendedj 

// Set the underline decoration to a TextDecorationCollection and add it to the text block. 
TextDecorationCollection myCollection = new TextDecorationCollection(); 
myCollection.Add(myUnderline); 

TextBlock2.TextDecorations = myCollection; 


' Use a Red pen for the underline text decoration. 

Private Sub SetRedUnderline() 

' Create an underline text decoration. Default is underline. 

Dim myUnderline As New TextDecoration() 

' Create a solid color brush pen for the text decoration. 
myUnderline.Pen = New Pen(Brushes.Redj 1) 

myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommended 

' Set the underline decoration to a TextDecorationCollection and add it to the text block. 
Dim myCollection As New TextDecorationCollection() 
myCollection.Add(myUnderline) 

TextBlock2.TextDecorations = myCollection 
End Sub 




<!-- Use a Red pen for the underline text decoration --> 
<TextBlock 

FontSize="36" > 
jumps over 

<TextBlock.TextDecorations> 

<TextDecorationCollection> 

cTextDecoration 

PenThicknessUnlt="FontRecommended"> 

<TextDecoration.Pen> 

<Pen Brush="Red" Thickness="l" /> 
</TextDecoration.Pen> 

</TextDecoration> 

</TextDecorationCollection> 

</TextBlock.TextDecorations> 

</TextBlock> 


In the following code exannple, an underline text decoration is created with a linear gradient brush for the dashed 
pen. 

// Use a linear gradient pen for the underline text decoration, 
private void SetLinearGradientUnderline() 

{ 

// Create an underline text decoration. Default is underline. 

TextDecoration myUnderline = new TextDecoration()j 

// Create a linear gradient pen for the text decoration. 

Pen my Pen = new Pen(); 

myPen.Brush = new LinearGradientBrush(Colors.Yellow^ Colors.Redj new Point(0, 0.5), new Point(l, 0.5)); 

myPen.Brush.Opacity = 0.5; 

myPen.Thickness = 1.5; 

myPen.DashStyle = DashStyles.Dash; 

myUnderline.Pen = myPen; 

myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommended; 

// Set the underline decoration to a TextDecorationCollection and add it to the text block. 
TextDecorationCollection myCollection = new TextDecorationCollection(); 
myCollection.Add(myUnderline); 

TextBlockB.TextDecorations = myCollection; 


' Use a linear gradient pen for the underline text decoration. 

Private Sub SetLinearGradientUnderline() 

' Create an underline text decoration. Default is underline. 

Dim myUnderline As New TextDecoration() 

' Create a linear gradient pen for the text decoration. 

Dim myPen As New Pen() 

myPen.Brush = New LinearGradientBrush(Colors.Yellow, Colors.Red, New Point(0, 0.5), New Point(l, 0.5)) 

myPen.Brush.Opacity = 0.5 

myPen.Thickness = 1.5 

myPen.DashStyle = DashStyles.Dash 

myUnderline.Pen = myPen 

myUnderline.PenThicknessUnit = TextDecorationUnit.FontRecommended 

' Set the underline decoration to a TextDecorationCollection and add it to the text block. 

Dim myCollection As New TextDecorationCollection() 
myCollection.Add(myUnderline) 

TextBlockB.TextDecorations = myCollection 
End Sub 




<!-- Use a linear gradient pen for the underline text decoration. --> 
<TextBlock FontSize="36">the lazy brown dog. 

<TextBlock.TextDecorations> 

<TextDecorationCollection> 

<TextDecoration 

PenThicknessUnit="FontRecommended"> 

<TextDecoration.Pen> 

<Pen Thickness="1.5"> 

<Pen.Brush> 

<LinearGradientBrush Opacity="0.5" 

StartPoint="0,0.5" EndPoint="lj0.5"> 

<LinearGradientBrush.GradientStops> 

cGradientStop Color="Yellow" Offset="0" /> 
<GradientStop Color="Red" Offset="l" /> 
</LinearGradientBrush.GradientStops> 
</LinearGradientBrush> 

</Pen.Brush) 

<Pen.DashStyle> 

<DashStyle Dashes="2"/> 

</Pen.DashStyle> 

</Pen> 

</TextDecoration.Pen> 

</TextDecoration> 

</TextDecorationCollection> 

</TextBlock.TextDecorations> 

</TextBlock> 


See also 

• TextDecoration 

• Hyperlink 

• Specify Whether a Hyperlink is Underlined 



How to: Specify Whether a Hyperlink is Underlined 

4/8/2019 • 2 minutes to read ^ Edit Online 


The Hyperlink object is an inline-level flow content element that allows you to host hyperlinks within the flow 
content. By default, Hyperlink uses a TextDecoration object to display an underline. TextDecoration objects can be 
performance intensive to instantiate, particularly if you have many Hyperlink objects. If you make extensive use of 
Hyperlink elements, you may want to consider showing an underline only when triggering an event, such as the 
MouseEnter event. 


In the following example, the underline for the "My MSN" link is dynamic, that is, it only appears when the 
MouseEnter event is triggered. 




Example 

The following markup sample shows a Hyperlink defined with and without an underline: 

<!-- Hyperlink with default underline. --> 

<Hyperlink NavigateLlri="http: //www. msn. com"> 

MSN Home 
</Hyperlink> 

<Run Text=" | " /> 

<!-- Hyperlink with no underline. --> 

<Hyperlink Name="myHyperlink" TextDecorations="None" 

MouseEnter="OnMouseEnter" 

MouseLeave="OnMouseLeave" 

NavigateUri="http://www.msn.com"> 

My MSN 
</Hyperlink> 


The following code sample shows how to create an underline for the Hyperlink on the MouseEnter event, and 
remove it on the MouseLeave event. 


// Display the underline on only the MouseEnter event, 
private void OnMouseEnter(object sender, EventArgs e) 

{ 

myHyperlink.TextDecorations = TextDecorations.Underline; 

} 

// Remove the underline on the MouseLeave event, 
private void OnMouseLeave(object sender, EventArgs e) 

{ 

myHyperlink.TextDecorations = null; 

} 




















' Display the underline on only the MouseEnter event. 

Private Overloads Sub OnMouseEnter(By\/al sender As Object^ ByVal e As EventArgs) 
myhlyperlink.TextDecorations = TextDecorations.Underline 
End Sub 

' Remove the underline on the MouseLeave event. 

Private Overloads Sub OnMouseLeave(By\/al sender As Object^ ByVal e As EventArgs) 
myhlyperlink.TextDecorations = Nothing 
End Sub 


See also 

• TextDecoration 

• Hyperlink 

• Optimizing WPF Application Performance 

• Create a Text Decoration 



How to: Apply Transforms to Text 

3/12/2020 • 2 minutes to read i Edit Online 


Transforms can alter the display of text in your application. The following examples use different types of rendering 
transforms to affect the display of text in a TextBlock control. 

Example 

The following example shows text rotated about a specified point in the two-dimensional x-y plane. 



The following code example uses a RotateTransform to rotate text. An Angle value of 90 rotates the element 90 
degrees clockwise. 

<!-- Rotate the text 90 degrees using a RotateTransform. --> 

<TextBlocl< FontFamily="Arial Black" FontSize="64" Foreground="Moccasin" Margin ="80, 10, 0, 0"> 

Text Transforms 
<TextBlock.RenderTransform> 

<RotateTransform Angle="90" /> 

</TextBlock.RenderTransform> 

</TextBlock> 


The following example shows the second line of text scaled by 150% along the x-axis, and the third line of text 
scaled by 150% along the y-axis. 

Scaled Text 

Scaled Text 

Scaled Text 


The following code example uses a ScaleTransform to scale text from its original size. 





<!-- Scale the text using a ScaleTransform. --> 
cTextBlock 

Name="textblockScaleMasten" 

FontSize="32" 

Foregnound="SteelBlue" 

Text="Scaled Text" 

Margin="100j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="0"> 

</TextBlock> 

<TextBlock 

FontSize="32" 

FontWeight="Bold" 

Foregnound="SteelBlue" 

Text="{Binding Path=Textj ElementName=textblockScaleMaster}" 
Margin="100j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="1"> 

<TextBlock.RenderTransform> 

<ScaleTnansform ScaleX="1.5" ScaleY="1.0" /> 

</TextBlock.RendenTransfonm> 

</TextBlock> 

<TextBlock 

FontSize="32" 

FontWeight="Bold" 

Foregnound="SteelBlue" 

Text="{Bindlng Patb=Text, ElementName=textblockScaleMaster}" 
Margin="100j 0 , 0 , 0 " 

Gnid.Column="0" Grid.Row="2"> 

<TextBlock.RenderTransform> 

<ScaleTnansfonm ScaleX="1.0" ScaleY="1.5" /> 

</TextBlock.RendenTransfonm> 

</TextBlock> 


NOTE 


Scaling text is not the same as increasing the font size of text. Font sizes are calculated independently of each other in order 
to provide the best resolution at different sizes. Scaled text, on the other hand, preserves the proportions of the original¬ 
sized text. 


The following exannple shows text skewed along the x-axis. 




The following code example uses a SkewTransform to skew text. A skew, also known as a shear, is a transformation 
that stretches the coordinate space in a non-uniform manner. In this example, the two text strings are skewed -30° 
and 30° along the x-coordinate. 




<!-- Skew the text using a SkewTransfortn. --> 

<TextBlock 

Name="textblockSkewMaster" 

FontSize="32" 

FontWeight="Bold" 

Foregnound="Maroon" 

Text="Skewed Text" 

Margin="125j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="0"> 

<TextBlock.RenderTransform> 

<SkewTransform AngleX="-30" AngleY="0" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

<TextBlock 

FontSize="32" 

FontWeight="Bold" 

Foreground="Maroon" 

Text="{Binding Path=Text, ElementName=textblockSkewMaster}" 

Margin="100j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="1"> 

<TextBlock.RenderTransform> 

<SkewTransform AngleX="30" AngleY="0" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

The following example shows text translated, or moved, along the x- and y-axis. 



Translated 


The following code example uses a TranslateTransform to offset text. In this example, a slightly offset copy of text 
below the primary text creates a shadow effect. 

<!-- Skew the text using a TranslateTransform. --> 

<TextBlock 

FontSize="32" 

FontWeight="Bold" 

Foreground="Black" 

Text="{Binding Path=Text, ElementName=textblockTranslateMaster}" 

Margin="100j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="0"> 

<TextBlock.RenderTransform> 

<TranslateTransform X="2" Y="2" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

cTextBlock 

Name="textblockTranslateMaster" 

FontSize="32" 

FontWeight="Bold" 

Foreground="Coral" 

Text="Translated Text" 

Margin="100j 0 , 0 , 0 " 

Grid.Column="0" Grid.Row="0"/> 


NOTE 


The DropShadowBitmapEffect provides a rich set of features for providing shadow effects. For more information, see Create 
Text with a Shadow. 


See also 





Apply Animations to Text 


How to: Apply Animations to Text 

3/12/2020 • 2 minutes to read ^ Edit Online 


Animations can alter the display and appearance of text in your application. The following examples use different 
types of animations to affect the display of text in a TextBlock control. 

Example 

The following example uses a DoubleAnimation to animate the width of the text block. The width value changes 
from the width of the text block to 0 over a duration of 10 seconds, and then reverses the width values and 
continues. This type of animation creates a wipe effect. 

<TextBlock 

Name="MyWipedText" 

Margin="20" 

Width="480" Height="100" FontSize="48" FontWeight="Bold" Foreground="Maroon"> 

This is wiped text 

<!-- Animates the text block's width. --> 

<TextBlock.Triggens> 

<EventTnigger RoutedEvent="TextBlock.Loaded"> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimation 

Storyboard.TargetName="MyWipedText" 

Storyboard.TargetProperty="(TextBlock.Width)" 

To="0.0" Duration="0:0:10" 

AutoReverse="True" RepeatBehavior="Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</TextBlock.Triggers> 

</TextBlock> 


The following example uses a DoubleAnimation to animate the opacity of the text block. The opacity value changes 
from 1.0 to 0 over a duration of 5 seconds, and then reverses the opacity values and continues. 





<TextBlocl< 

Name="MyFadingText" 

Margin="20" 

Width="640" Height="100" FontSize="48" FontWeight="Bold" Foreground="Maroon"> 
This is fading text 

<!-- Animates the text block's opacity. --> 

<TextBlock.Trlggens> 

<EventTrigger RoutedEvent="TextBlock.Loaded"> 

<BeginStoryboard> 

<Storyboard> 

<DoubleAnimatlon 

Storyboard.TargetName="MyFadingText" 

Storyboard.TargetProperty="(TextBlock.Opacity)" 

From="1.0" To="0.0" Duration="0:0:5" 

AutoReverse="True" RepeatBehavior="Forever" /> 

</Storyboard> 

</BeginStoryboard> 

</EventTrigger> 

</TextBlock.Triggers> 

</TextBlock> 


The following diagram shows the effect of the TextBlock control changing its opacity from 1.00 to 0.00 during 
the 5-second interval defined by the Duration. 
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The following example uses a ColorAnimation to animate the foreground color of the text block. The foreground 
color value changes from one color to a second color over a duration of 5 seconds, and then reverses the color 
values and continues. 





<TextBlocl< 

Name="MyChangingColorText" 

Margin="20" 

Width="640" Height="100" FontSize="48" FontWeight="Bold"> 

This is changing color text 
cTextBlock.Foreground> 

cSolidColorBrush x:Name="MySolidColorBrush" Color="Maroon" /> 
</TextBlock.Foreground) 

<!-- Animates the text block's color. --> 

<TextBlock.Triggers) 

<EventTrigger RoutedEvent="TextBlock.Loaded") 

<BeginStoryboard) 

<Storyboard) 

<ColorAnimation 

Storyboard.TargetName="MySolidColorBrush" 

Storyboard.TargetProperty="Color" 

From="DarkOrange" To="SteelBlue" Duration="0:0:5" 
AutoReverse="True" RepeatBehavior="Forever" /) 
</Storyboard) 

</BeginStoryboard) 

</EventTrigger) 

</TextBlock.Triggers) 

</TextBlock) 


The following example uses a DoubleAnimation to rotate the text block. The text block performs a full rotation over 
a duration of 20 seconds, and then continues to repeat the rotation. 

<TextBlock 

Name="MyRotatingText" 

Margin="20" 

Width="640" Height="100" FontSize="48" FontWeight="Bold" Foreground="Teal" 

) 

This is rotating text 
<TextBlock.RenderTransform) 

<RotateTransform x:Name="MyRotateTransform" Angle="0" CenterX="230" CenterY="25"/) 

</TextBlock.RenderTransform) 

<!-- Animates the text block's rotation. --) 

<TextBlock.Triggers) 

<EventTrigger RoutedEvent="TextBlock.Loaded") 

<BeginStoryboard) 

<Storyboard) 

<DoubleAnimation 

Storyboard.TargetName="MyRotateTransform" 

Storyboard.TargetProperty="(RotateTransform.Angle)" 

From="0.0" To="360" Duration="0:0:10" 

RepeatBehavior="Forever" /) 

</Storyboard) 

</BeginStoryboard) 

</EventTrigger) 

</TextBlock.Triggers) 

</TextBlock) 


See also 


• Animation Overview 




How to: Create Text with a Shadow 

3/12/2020 • 2 minutes to read ^ Edit Online 


The examples in this section show how to create a shadow effect for displayed text. 

Example 

The DropShadowEffect object allows you to create a variety of drop shadow effects for Windows Presentation 
Foundation (WPF) objects. The following example shows a drop shadow effect applied to text. In this case, the 
shadow is a soft shadow, which means the shadow color blurs. 

Shadow Text 


You can control the width of a shadow by setting the ShadowDepth property. A value of 4.0 indicates a shadow 
width of 4 pixels. You can control the softness, or blur, of a shadow by modifying the BlurRadius property. A value 
of 0.0 indicates no blurring. The following code example shows how to create a soft shadow. 

<!-- Soft single shadow. --> 
sTextBlock 

Text="Shadow Text" 

Foregnound="Teal"> 
sTextBlock.Effect> 

<DropShadowEffect 

ShadowDepth="4" 

Dlrection="330" 

Color="Black" 

Opacity="0.5" 

BlurRadius="4"/> 

</TextBlock.Effect> 

</TextBlock> 



The following example shows a hard drop shadow effect applied to text. In this case, the shadow is not blurred. 

Shadow Text 


You can create a hard shadow by setting the BlurRadius property to 0.0 , which indicates that no blurring is used. 
You can control the direction of the shadow by modifying the Direction property. Set the directional value of this 
property to a degree between 0 and 360 . The following illustration shows the directional values of the Direction 
property setting. 
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The following code example shows how to create a hard shadow. 

<!-- Hard single shadow. --> 

<TextBlocl< 

Text="Shadow Text" 

Foreground="Maroon"> 

<TextBlocl<. Effect> 

<DropShadowEffect 

ShadowDepth="6" 

Direction="135" 

Color="Maroon" 

Opacity="0.35" 

BlurRadius="0.0" /> 

</TextBlock.Effect) 

</TextBlock> 


Using a Blur Effect 


A BlurBitmapEffect can be used to create a shadow-like effect that can be placed behind a text object. A blur bitmap 
effect applied to text blurs the text evenly in all directions. 

The following example shows a blur effect applied to text. 



The following code example shows how to create a blur effect. 



<!-- Shadow effect by creating a blur. --> 
<TextBlock 

Text="Shadow Text" 

Foreground="Green" 

Grid.Column="0" Grid.Row="0" > 
cTextBlock.Effect> 

<BlurEffect 

Radius="8.0" 

KernelType="Box"/> 

</TextBlock.Effect> 

</TextBlock> 

<TextBlock 

Text="Shadow Text" 

Foreground="Maroon" 

Grid.Column="0" Grid.Row="0" /> 


Using a Translate Transform 


A TranslateTransform can be used to create a shadow-like effect that can be placed behind a text object. 

The following code example uses a TranslateTransform to offset text. In this example, a slightly offset copy of text 
below the primary text creates a shadow effect. 



The following code example shows how to create a transform for a shadow effect. 


<!-- Shadow effect by creating a transform. --> 
<TextBlock 

Foreground="Black" 

Text="Shadow Text" 

Grid.Column="0" Grid.Row="0"> 
<TextBlock.RenderTransform> 

<TranslateTransform X="3" Y="3" /> 

</TextBlock.RenderTransform> 

</TextBlock> 

<TextBlock 

Foreground="Coral" 

Text="Shadow Text" 

Grid.Column="0" Grid.Row="0"> 


</TextBlock> 




How to: Create outlined text 

4/14/2020 • 3 minutes to read ^ Edit Online 


In most cases, when you're adding ornamentation to text strings in your Windows Presentation Foundation (WPF) 
application, you are using text in terms of a collection of discrete characters, or glyphs. For example, you could 
create a linear gradient brush and apply it to the Foreground property of a TextBox object. When you display or 
edit the text box, the linear gradient brush is automatically applied to the current set of characters in the text string. 

Spectrum Foreground 

However, you can also convert text into Geometry objects, allowing you to create other types of visually rich text. 
For example, you could create a Geometry object based on the outline of a text string. 



[nm 


When text is converted to a Geometry object, it is no longer a collection of characters—you cannot modify the 
characters in the text string. However, you can affect the appearance of the converted text by modifying its stroke 
and fill properties. The stroke refers to the outline of the converted text; the fill refers to the area inside the outline 
of the converted text. 

The following examples illustrate several ways of creating visual effects by modifying the stroke and fill of 
converted text. 



• S/R ‘ '1 ‘ -Jjl 

It is also possible to modify the bounding box rectangle, or highlight, of the converted text. The following example 
illustrates a way to create visual effects by modifying the stroke and highlight of converted text. 



Example 

The key to converting text to a Geometry object is to use the FormattedText object. Once you have created this 
object, you can use the BuildGeometry and BuildHighlightGeometry methods to convert the text to Geometry 
objects. The first method returns the geometry of the formatted text; the second method returns the geometry of 
the formatted text's bounding box. The following code example shows how to create a FormattedText object and to 
retrieve the geometries of the formatted text and its bounding box. 










Ill <summary> 

III Create the outline geometry based on the formatted text. 

Ill </summary> 

public void CreateText() 

{ 

System.Windows.FontStyle fontStyle = FontStyles.Normal; 

FontWeight fontWeight = FontWeights.Medium; 

if (Bold == true) fontWeight = FontWeights.Bold; 
if (Italic == true) fontStyle = FontStyles.Italic; 

// Create the formatted text based on the properties set. 

FormattedText formattedText = new FormattedText( 

Text j 

CultureInfo.GetCultureInfo("en-us "), 

FlowDirection.LeftToRightj 
new Typeface( 

Font j 

fontStyle, 

fontWeight, 

FontStretches.Normal), 

FontSize, 

System.Windows.Media.Brushes.Black // This brush does not matter since we use the geometry of the 

text. 

); 

// Build the geometry object that represents the text. 

_textGeometry = formattedText.BuildGeometry(new System.Windows.Point(0, 0)); 

// Build the geometry object that represents the text highlight, 
if (Highlight == true) 

{ 

_textHighLightGeometry = formattedText.BuildHighlightGeometry(new System.Windows.Point(0, 0)); 

} 


''' <summary> 

''' Create the outline geometry based on the formatted text. 

''' </summary> 

Public Sub CreateTextO 

Dim fontStyle As FontStyle = FontStyles.Normal 
Dim fontWeight As FontWeight = FontWeights.Medium 

If Bold = True Then 

fontWeight = FontWeights.Bold 
End If 

If Italic = True Then 

fontStyle = FontStyles.Italic 
End If 

' Create the formatted text based on the properties set. 

Dim formattedText As New FormattedText(Text, CultureInfo.GetCultureInfo("en-us"), 

FlowDirection.LeftToRight, New Typeface(Font, fontStyle, fontWeight, FontStretches.Normal), FontSize, 
Brushes.Black) ' This brush does not matter since we use the geometry of the text. 

' Build the geometry object that represents the text. 

_textGeometry = formattedText.BuildGeometry(New Point(0, 0)) 

' Build the geometry object that represents the text highlight. 

If Highlight = True Then 

_textHighLightGeometry = formattedText.BuildHighlightGeometry(New Point(0, 0)) 

End If 
End Sub 


In order to display the retrieved the Geometry objects, you need to access the DrawingContext of the object that's 



displaying the converted text. In these code examples, this access is achieved by creating a custom control object 
that's derived from a class that supports user-defined rendering. 

To display Geometry objects in the custom control, provide an override for the OnRender method. Your overridden 
method should use the DrawGeometry method to draw the Geometry objects. 

Ill <summary> 

III OnRender override draws the geometry of the text and optional highlight. 

Ill </summary> 

III <param name="drawingContext">Drawing context of the OutlineText control.</param> 
protected override void OnRender(DrawingContext drawingContext) 

{ 

// Draw the outline based on the properties that are set. 

drawingContext.DrawGeometry(Fillj new System.Windows.Media.Pen(Stroke, StrokeThickness), _textGeometry); 

// Draw the text highlight based on the properties that are set. 
if (Highlight == true) 

{ 

drawingContext.DrawGeometry(nullj new System.Windows.Media.Pen(Stroke, StrokeThickness)^ 
_textHighLightGeometry); 

} 

} 


''' <summary> 

''' OnRender override draws the geometry of the text and optional highlight. 

''' </summary> 

<param name="drawingContext">Drawing context of the OutlineText control.</param> 

Protected Overrides Sub OnRender(ByVal drawingContext As DrawingContext) 

' Draw the outline based on the properties that are set. 

drawingContext.DrawGeometry(Fill^ New Pen(Strokej StrokeThickness)j _textGeometry) 

' Draw the text highlight based on the properties that are set. 

If Highlight = True Then 

drawingContext.DrawGeometry(Nothing, New Pen(Stroke, StrokeThickness), _textHighLightGeometry) 
End If 
End Sub 


For the source of the example custom user control object, see OutlineTextControl.es for C# and 
OutlineTextControl.vb for Visual Basic. 

See also 


• Drawing Formatted Text 



How to: Draw Text to a Control's Background 

11/1/2019 • 2 minutes to readi Edit Online 


You can draw text directly to the background of a control by converting a text string to a FormattedText object, and 
then drawing the object to the control's DrawingContext. You can also use this technique for drawing to the 
background of objects derived from Panel, such as Canvas and StackPanel. 

My Custom Label Display Text | 

Example of controls with custom text backgrounds 

Example 

To draw to the background of a control, create a new DrawingBrush object and draw the converted text to the 
object's DrawingContext. Then, assign the new DrawingBrush to the control's background property. 

The following code example shows how to create a FormattedText object and draw to the background of a Label 
and Button object. 





// Handle the WindowLoaded event for the window, 
private void WindowLoaded(object sender^ EventArgs e) 

{ 

// Update the background property of the label and button. 
myLabel.Background = new DrawingBrush(DrawMyText("My Custom Label"))j 
myButton.Background = new DrawingBrush(DrawMyText("Display Text"))j 

} 

// Convert the text string to a geometry and draw it to the control's DrawingContext. 
private Drawing DrawMyText(string textstring) 

{ 

// Create a new DrawingGroup of the control. 

DrawingGroup drawingGroup = new DrawingGroupOj 

// Open the DrawingGroup in order to access the DrawingContext. 
using (DrawingContext drawingContext = drawingGroup.Open()) 

{ 

// Create the formatted text based on the properties set. 

FormattedText formattedText = new FormattedText( 
textstring, 

CultureInfo.GetCultureInfo("en-us"), 

FlowDirection.LeftToRight, 

new Typeface("Comic Sans MS Bold"), 

48, 

System.Windows.Media.Brushes.Black // This brush does not matter since we use the geometry of the 

text. 

); 

// Build the geometry object that represents the text. 

Geometry textGeometry = formattedText.BuildGeometry(new System.Windows.Point(20, 0)); 

// Draw a rounded rectangle under the text that is slightly larger than the text. 
drawingContext.DrawRoundedRectangle(System.Windows.Media.Brushes.PapayaWhip, null, new Rect(new 
System.Windows.Size(formattedText.Width + 50, formattedText.Height + 5)), 5.0, 5.0); 

// Draw the outline based on the properties that are set. 
drawingContext.DrawGeometry(System.Windows.Media.Brushes.Gold, new 
System.Windows.Media.Pen(System.Windows.Media.Brushes.Maroon, 1.5), textGeometry); 

// Return the updated DrawingGroup content to be used by the control, 
return drawingGroup; 

} 

} 


See also 


• FormattedText 

• Drawing Formatted Text 



How to: Draw Text to a Visual 
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The following example shows how to draw text to a DrawingVisual using a DrawingContext object. A drawing 
context is returned by calling the RenderOpen method of a DrawingVisual object. You can draw graphics and text 
into a drawing context. 

To draw text into the drawing context, use the DrawText method of a DrawingContext object. When you are finished 
drawing content into the drawing context, call the Close method to close the drawing context and persist the 
content. 

Example 

// Create a DrawingVisual that contains text, 
private DrawingVisual CreateDrawingVisualText() 

{ 

// Create an instance of a DrawingVisual. 

DrawingVisual drawingVisual = new DrawingVisual(); 

// Retrieve the DrawingContext from the DrawingVisual. 

DrawingContext drawingContext = drawingVisual.RenderOpen()j 

// Draw a formatted text string into the DrawingContext. 
drawingContext.DrawText( 

new FormattedText("Click Me!"j 

CultureInfo.GetCultureInfo("en-us"), 

FlowDirection.LeftToRightj 
new Typeface("Verdana")j 
36j System.Windows.Media.Brushes.Black), 
new System.Windows.Point(200, 116)); 

// Close the DrawingContext to persist changes to the DrawingVisual. 
drawingContext.Close(); 

return drawingVisual; 

} 


' Create a DrawingVisual that contains text. 

Private Function CreateDrawingVisualText() As DrawingVisual 
' Create an instance of a DrawingVisual. 

Dim drawingVisual As New DrawingVisual() 

' Retrieve the DrawingContext from the DrawingVisual. 

Dim drawingContext As DrawingContext = drawingVisual.RenderOpen() 

' Draw a formatted text string into the DrawingContext. 

drawingContext.DrawText(New FormattedText("Click Me!", CultureInfo.GetCultureInfo("en-us"), 
FlowDirection.LeftToRlght, New Typeface("Verdana"), 36, Brushes.Black), New Point(200, 116)) 

' Close the DrawingContext to persist changes to the DrawingVisual. 
drawingContext.Close() 

Return drawingVisual 
End Function 





NOTE 

For the complete code sample from which the preceding code example was extracted, see Hit Test Using DrawingVisuals 
Sample. 



How to: Use Special Characters in XAML 
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Markup files that are created in Visual Studio are automatically saved in the Unicode UTF-8 file format, which 
means that most special characters, such as accent marks, are encoded correctly. However, there is a set of 
commonly-used special characters that are handled differently. These special characters follow the World Wide 
Web Consortium (W3C) XML standard for encoding. 

The following table shows the syntax for encoding this set of special characters: 


CHARACTER 

SYNTAX 

DESCRIPTION 

< 

ait; 

Less than symbol. 

> 

&gt; 

Greater than sign. 


& 


&amp; 


Ampersand symbol. 


&quotj 


Double quote symbol. 


NOTE 

If you create a markup file using a text editor, such as Windows Notepad, you must save the file in the Unicode UTF-8 file 
format in order to preserve any encoded special characters. 


The following example shows how you can use special characters in text when creating markup. 


Example 


<!-- Display special characters that require special encoding: < > & " 

<TextBlocl<> 

&lt; <!-- Less than symbol --> 

&gt; <!-- Greater than symbol --> 

Samp; <!-- Ampersand symbol --> 

Squot; <!-- Double quote symbol --> 

</TextBlock> 

--> 

<!-- Display miscellaneous special characters --> 

<TextBlocl<> 

Caesar <!-- AE dipthong symbol --> 

© 2006 <!-- Copyright symbol --> 

Espanol <!-- Tilde symbol --> 

¥ <!-- Yen symbol --> 

</TextBlock> 











Printing and Print System Management 

11/12/2019 • 2 minutes to read ^ Edit Online 


Windows Vista and Microsoft .NET Framework introduce a new print path — an alternative to Microsoft Windows 
Graphics Device Interface (GDI) printing — and a vastly expanded set of print system management APIs. 

In This Section 

Printing Overview 

A discussion of the new print path and APIs. 

How-to Topics 

A set of articles showing how to use the new print path and APIs. 

See also 

• System.Printing 

• System.Printing.IndexedProperties 

• System.Printing.Interop 

• Documents in WPF 

• XPS Documents 




Printing Overview 
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With Microsoft .NET Framework, application developers using Windows Presentation Foundation (WPF) have a 
rich new set of printing and print system management APIs. With Windows Vista, some of these print system 
enhancements are also available to developers creating Windows Forms applications and developers using 
unmanaged code. At the core of this new functionality is the new XML Paper Specification (XPS) file format and 
the XPS print path. 

This topic contains the following sections. 


About XPS 


XPS is an electronic document format, a spool file format and a page description language. It is an open 
document format that uses XML, Open Packaging Conventions (OPC), and other industry standards to create 
cross-platform documents. XPS simplifies the process by which digital documents are created, shared, printed, 
viewed, and archived. For additional information on XPS, see XPS Documents. 

Several techniques for printing XPS-based content using WPF are demonstrated in Programmatically Print XPS 
Files. You may find it useful to reference these samples during review of content contained in this topic. 
(Unmanaged code developers should see documentation for the MXDC_ESCAPE function. Windows Forms 
developers must use the API in the System.Drawing.Printing namespace which does not support the full XPS 
print path, but does support a hybrid GDI-to-XPS print path. See Print Path Architecture below.) 


XPS Print Path 


The XML Paper Specification (XPS) print path is a new Windows feature that redefines how printing is handled in 
Windows applications. Because XPS can replace a document presentation language (such as RTF), a print spooler 
format (such as WMF), and a page description language (such as PCL or Postscript); the new print path maintains 
the XPS format from application publication to the final processing in the print driver or device. 

The XPS print path is built upon the XPS printer driver model (XPSDrv), which provides several benefits for 
developers such as "what you see is what you get" (WYSIWYG) printing, improved color support, and 
significantly improved print performance. (For more on XPSDrv, see the Windows Driver Kit documentation.) 

The operation of the print spooler for XPS documents is essentially the same as in previous versions of Windows. 
However, it has been enhanced to support the XPS print path in addition to the existing GDI print path. The new 
print path natively consumes an XPS spool file. While user-mode printer drivers written for previous versions of 
Windows will continue to work, an XPS printer driver (XPSDrv) is required in order to use the XPS print path. 

The benefits of the XPS print path are significant, and include: 

• WYSIWYG print support 

• Native support of advanced color profiles, which include 32 bits per channel (bpc), CMYK, named-colors, 
n-inks, and native support of transparency and gradients. 

• Improved print performance for both .NET Framework and Win32 based applications. 

• Industry standard XPS format. 

For basic print scenarios, a simple and intuitive API is available with a single entry point for user interface, 
configuration and job submission. For advanced scenarios, an additional support is added for user interface (Ul) 




customization (or no Ul at all), synchronous or asynchronous printing, and batch printing capabilities. Both 
options provide print support in full or partial trust mode. 

XPS was designed with extensibility in mind. By using the extensibility framework, features and capabilities can 
be added to XPS in a modular manner. Extensibility features include: 

• Print Schema. The public schema is updated regularly and enables rapid extension of device capabilities. 

(See PrintTicket and PrintCapabilities below.) 

• Extensible Filter Pipeline. The XPS printer driver (XPSDrv) filter pipeline was designed to enable both direct 
and scalable printing of XPS documents. For more information, see XPSDrv Printer Drivers. 

Print Path Architecture 

While both Win32 and .NET Framework applications support XPS, Win32 and Windows Forms applications use a 
GDI to XPS conversion in order to create XPS formatted content for the XPS printer driver (XPSDrv). These 
applications are not required to use the XPS print path, and can continue to use Enhanced Metafile (EMF) based 
printing. However, most XPS features and enhancements are only available to applications that target the XPS 
print path. 

To enable the use of XPSDrv-based printers by Win32 and Windows Forms applications, the XPS printer driver 
(XPSDrv) supports conversion of GDI to XPS format. The XPSDrv model also provides a converter for XPS to GDI 
format so that Win32 applications can print XPS Documents. For WPF applications, conversion of XPS to GDI 
format is done automatically by the Write and WriteAsync methods of the XpsDocumentWriter class whenever 
the target print queue of the write operation does not have an XPSDrv driver. (Windows Forms applications 
cannot print XPS Documents.) 

The following illustration depicts the print subsystem and defines the portions provided by Microsoft, and the 
portions defined by software and hardware vendors: 

Win32 WPF 

Application Application 



ISV 

Microsoft 

IHV 


Basic XPS Printing 

WPF defines both a basic and advanced API. For those applications that do not require extensive print 
customization or access to the complete XPS feature set, basic print support is available. Basic print support is 
exposed through a print dialog control that requires minimal configuration and features a familiar Ul. Many XPS 
features are available using this simplified print model. 

PrintDialog 

The System.Windows.Controls.PrintDialog control provides a single entry point for Ul, configuration, and XPS job 
submission. For information about how to instantiate and use the control, see Invoke a Print Dialog. 
























Advanced XPS Printing 

To access the complete set of XPS features, the advanced print API must be used. Several relevant API are 
described in greater detail below. For a complete list of XPS print path APIs, see the System.Windows.Xps and 
System.Printing namespace references. 

PrintTicket and PrintCapabilities 

The PrintTicket and PrintCapabilities classes are the foundation of the advanced XPS features. Both types of 
objects are XML formatted structures of print-oriented features such as collation, two-sided printing, stapling, etc. 
These structures are defined by the print schema. A PrintTicket instructs a printer how to process a printjob. The 
PrintCapabilities class defines the capabilities of a printer. By querying the capabilities of a printer, a PrintTicket 
can be created that takes full advantage of a printer's supported features. Similarly, unsupported features can be 
avoided. 

The following example demonstrates how to query the PrintCapabilities of a printer and create a PrintTicket 
using code. 

// - GetPrintTicketFromPninter - 

III <summary> 

III Returns a PrintTicket based on the current default printer.</summary> 

III <returns> 

III A PrintTicket for the current local default printer.</returns> 

PrintTicket'' GetPrintTicketFromPninter () 

{ 

PrintQueue'' printQueue = nullptr; 

LocalPrintServer'' localPrintServer = gcnew LocalPrintServer(); 

// Retrieving collection of local printer on user machine 

PrintQueueCollection'' localPrinterCollection = localPrintServer->GetPrintQueues(); 

System::Collections::lEnumerator^ localPrinterEnumerator = localPrinterCollection->GetEnumerator(); 

if (localPrinterEnumerator->MoveNext()) 

{ 

// Get PrintQueue from first available printer 
printQueue = ((PrintQueue^)localPrinterEnumerator->Current)j 
} else 
{ 

return nullptr; 

} 

// Get default PrintTicket from printer 

PrintTicket'' printTicket = printQueue->DefaultPrintTicket; 

PrintCapabilities'' printCapabilltes = printQueue->GetPrintCapabilities()j 
// Modify PrintTicket 

if (printCapabilltes->CollationCapability->Contains(Collation::Collated)) 

{ 

printTicket->Collation = Collation::Collated; 

} 

if (printCapabilltes->DuplexingCapability->Contains(Duplexing::TwoSidedLongEdge)) 

{ 

printTicket-xDuplexing = Duplexing::TwoSidedLongEdge; 

} 

if (printCapabilltes->StaplingCapability->Contains(Stapling::StapleDualLeft)) 

{ 

printTicket-xStapling = Stapling::StapleDualLeft; 

} 

return printTicket; 

};// end:GetPrlntTicketFromPrinter() 





// - GetPrintTicketFromPninter - 

III <summary> 

III Returns a PrintTicket based on the current default printer.</summary> 

III <returns> 

III A PrintTicket for the current local default printer.</returns> 
private PrintTicket GetPrintTicketFromPrinter() 

{ 

PrintQueue printQueue = null; 

LocalPrintServer localPrintServer = new LocalPrintServer(); 

// Retrieving collection of local printer on user machine 
PrintQueueCollection localPrinterCollection = 
localPrintServer .GetPrintQueuesO; 

System.Collections.lEnumerator localPrinterEnumerator = 
localPrinterCollection.GetEnumerator0; 

if (localPrinterEnumerator.MoveNextO) 

{ 

// Get PrintQueue from first available printer 
printQueue = (PrintQueue)localPrinterEnumerator.Current; 

} 

else 

{ 

// No printer exists return null PrintTicket 
return null; 

} 

// Get default PrintTicket from printer 

PrintTicket printTicket = printQueue.DefaultPrintTicket; 

PrintCapabllities printCapabilites = printQueue.GetPrintCapabilities(); 

// Modify PrintTicket 

if (printCapabilites.CollationCapability.Contains(Collation.Collated)) 

{ 

printTicket.Collation = Collation.Collated; 

} 

if ( printCapabilites.DuplexingCapability.Contains( 

Duplexing.TwoSidedLongEdge) ) 

{ 

printTicket.Duplexing = Duplexing.TwoSidedLongEdge; 

} 

if (printCapabilites.StaplingCapability.Contains(Stapling.StapleDualLeft)) 

{ 

printTicket.Stapling = Stapling.StapleDualLeft; 

} 

return printTicket; 

}// end: Get PrintTicket FromPrinterO 





' - GetPrintTicketFromPrinter - 

' ' ' <summary> 

''' Returns a PrintTlcket based on the current default printer.</summary> 

' ' ' <returns> 

''' A PrintTicket for the current local default printer.</returns> 

Private Function GetPrintTicketFromPrinter() As PrintTicket 
Dim printQueue As PrintQueue = Nothing 

Dim localPrintServer As New LocalPrintServer() 

' Retrieving collection of local printer on user machine 

Dim localPrinterCollection As PrintQueueCollection = localPrintServer.GetPrintQueues() 

Dim localPrinterEnumerator As System.Collections.lEnumerator = localPrinterCollection.GetEnumerator() 

If localPrinterEnumerator.MoveNextO Then 

' Get PrintQueue from first available printer 

printQueue = CType(localPrinterEnumerator.Currentj PrintQueue) 

Else 

' No printer exists return null PrintTicket 
Return Nothing 
End If 

' Get default PrintTicket from printer 

Dim PrintTicket As PrintTicket = printQueue.DefaultPrintTicket 

Dim printCapabilites As PrintCapabilities = printQueue.GetPrintCapabilities() 

' Modify PrintTicket 

If printCapabilites.CollationCapability.Contains(Collation.Collated) Then 
printTicket.Collation = Collation.Collated 
End If 

If printCapabilites.DuplexingCapability.Contains(Duplexing.TwoSidedLongEdge) Then 
printTicket.Duplexing = Duplexing.TwoSidedLongEdge 
End If 

If printCapabilites.StaplingCapability.Contains(Stapling.StapleDualLeft) Then 
printTicket.Stapling = Stapling.StapleDualLeft 
End If 

Return printTicket 

End Function ' end:GetPrintTicketFromPrinter() 

PrintServer and PrintQueue 

The PrintServer class represents a network print server and the PrintQueue class represents a printer and the 
output job queue associated with it. Together, these APIs allow advanced management of a server's print jobs. A 
PrintServer, or one of its derived classes, is used to manage a PrintQueue. The AddJob method is used to insert a 
new print job into the queue. 

The following example demonstrates how to create a LocalPrintServer and access its default PrintQueue by using 
code. 






II -GetPnintXpsDocumentWriterO - 

III <summary> 

III Returns an XpsDocumentWriter for the default print queue.</summary> 
III <returns> 

III An XpsDocumentWriter for the default print queue.</returns> 


private XpsDocumentWriter GetPrintXpsDocumentWriter() 

{ 

// Create a local print server 
LocalPrintServer ps = new LocalPrintServer(); 

// Get the default print queue 
PrintQueue pq = ps.DefaultPrintQueue; 

// Get an XpsDocumentWriter for the default print queue 
XpsDocumentWriter xpsdw = PrintQueue.CreateXpsDocumentWriter(pq); 
return xpsdw; 

}// end:GetPnintXpsDocumentWriterO 


' -GetPnintXpsDocumentWriterO - 

' ' ' <summary> 

''' Returns an XpsDocumentWriter for the default print queue.</summary> 

' ' ' <returns> 

''' An XpsDocumentWriter for the default print queue.</returns> 

Private Function GetPnintXpsDocumentWriterO As XpsDocumentWriter 
' Create a local print server 
Dim ps As New LocalPrintServerO 

' Get the default print queue 

Dim pq As PrintQueue = ps.DefaultPrintQueue 

' Get an XpsDocumentWriter for the default print queue 

Dim xpsdw As XpsDocumentWriter = PrintQueue.CreateXpsDocumentWriter(pq) 

Return xpsdw 

End Function ' end:GetPrintXpsDocumentWriterO 

XpsDocumentWriter 

An XpsDocunnentWriter, with its many the Write and WriteAsync methods, is used to write XPS documents to a 
PrintQueue. For example, the Write(FixedPage, PrintTicket) method is used to output an XPS document and 
PrintTicket synchronously. The WriteAsync{FixedDocument, PrintTicket) method is used to output an XPS 
document and PrintTicket asynchronously. 

The following example demonstrates how to create an XpsDocumentWriter using code. 


II -GetPnintXpsDocumentWriterO - 

III <summary> 

III Returns an XpsDocumentWriter for the default print queue.</summary> 
III <returns> 

III An XpsDocumentWriter for the default print queue.</returns> 


private XpsDocumentWriter GetPnintXpsDocumentWriterO 

{ 

// Create a local print server 
LocalPrintServer ps = new LocalPrintServerO; 

// Get the default print queue 
PrintQueue pq = ps.DefaultPrintQueue; 

// Get an XpsDocumentWriter for the default print queue 
XpsDocumentWriter xpsdw = PrintQueue.CreateXpsDocumentWriter(pq); 
return xpsdw; 

}// end:GetPnintXpsDocumentWriterO 










' -GetPrintXpsDocumentWriterO - 

' ' ' <summary> 

''' Returns an XpsDocumentWriter for the default print queue.</summary> 

' ' ' <returns> 

''' An XpsDocumentWriter for the default print queue.</returns> 

Private Function GetPrintXpsDocumentWriterO As XpsDocumentWriter 
' Create a local print server 
Dim ps As New LocalPrintServer() 

' Get the default print queue 

Dim pq As PrintQueue = ps.DefaultPrintQueue 

' Get an XpsDocumentWriter for the default print queue 

Dim xpsdw As XpsDocumentWriter = PrintQueue.CreateXpsDocumentWriter(pq) 

Return xpsdw 

End Function ' end:GetPrintXpsDocumentWriter() 


The AddJob methods also provide ways to print. See Programmatically Print XPS Files, for details. 


GDI Print Path 


While WPF applications natively support the XPS print path, Win32 and Windows Forms applications can also 
take advantage of some XPS features. The XPS printer driver (XPSDrv) can convert GDI based output to XPS 
format. For advanced scenarios, custom conversion of content is supported using the Microsoft XPS Document 
Converter (MXDC). Similarly, WPF applications can also output to the GDI print path by calling one of the Write 
or WriteAsync methods of the XpsDocumentWriter class and designating a non-XpsDrv printer as the target 
print queue. 

For applications that do not require XPS functionality or support, the current GDI print path remains unchanged. 

• For additional reference material on the GDI print path and the various XPS conversion options, see Microsoft 
XPS Document Converter (MXDC) and XPSDrv Printer Drivers. 

XPSDrv Driver Model 

The XPS print path improves spooler efficiency by using XPS as the native print spool format when printing to an 
XPS -enabled printer or driver. The simplified spooling process eliminates the need to generate an intermediate 
spool file, such as an EMF data file, before the document is spooled. Through smaller spool file sizes, the XPS 
print path can reduce network traffic and improve print performance. 

EMF is a closed format that represents application output as a series of calls into GDI for rendering services. 
Unlike EMF, the XPS spool format represents the actual document without requiring further interpretation when 
output to an XPS-based printer driver (XPSDrv). The drivers can operate directly on the data in the format. This 
capability eliminates the data and color space conversions required when you use EMF files and GDI-based print 
drivers. 

Spool file sizes are usually reduced when you use XPS Documents that target an XPS printer driver (XPSDrv) 
compared with their EMF equivalents; however, there are exceptions: 

• A vector graphic that is very complex, multi-layered, or inefficiently written can be larger than a 
bitmapped version of the same graphic. 

• For screen display purposes, XPS files embed device fonts as well as computer-based fonts; whereas GDI 
spool files do not embed device fonts. But both kinds of fonts are subsetted (see below) and printer 
drivers can remove the device fonts before transmitting the file to the printer. 

Spool size reduction is performed through several mechanisms: 

• Font subsetting. Only characters used within the actual document are stored in the XPS file. 






• Advanced Graphics Support. Native support for transparency and gradient primitives avoids 
rasterization of content in the XPS Document 

• Identification of common resources. Resources that are used multiple times (such as an image that 
represents a corporate logo) are treated as shared resources and are loaded only once. 

• ZIP compression. All XPS documents use ZIP compression. 

See also 

• PrintDialog 

• XpsDocumentWriter 

• XpsDocument 

• PrintTicket 

• PrintCapabilities 

• PrintServer 

• PrintQueue 

• How-to Topics 

• Documents in WPF 

• XPS Documents 

• Document Serialization and Storage 

• Microsoft XPS Document Converter (MXDC) 


Printing How-to Topics 
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The topics in this section demonstrate how to use the printing and print system management features included 
with Windows Presentation Foundation (WPF) as well as the new XML Paper Specification (XPS) print path. 

In This Section 

Invoke a Print Dialog 

Instructions for XAML markup to declare a Microsoft Windows print dialog object and using code to invoke the 
dialog from within a Windows Presentation Foundation (WPF) application. 

Clone a Printer 

Instructions for how to install a second print queue with exactly the same properties as an existing print queue. 
Diagnose Problematic Print Job 

Instructions for using the properties of print queues and print jobs to diagnose a print job that is not printing. 
Discover Whether a Print Job Can Be Printed At This Time of Day 

Instructions for using the properties of print queues and print jobs to programmatically decide what times of day 
the job can be printed. 

Enumerate a Subset of Print Queues 

Instructions for generating a list of printers having certain characteristics. 

Get Print System Object Properties Without Reflection 

Instructions for how to discover at runtime print system object's properties and their types. 

Programmatically Print XPS Files 

Instructions for rapid printing of XML Paper Specification (XPS) files without the need for a user interface (Ul). 
Remotely Survey the Status of Printers 

Instructions for creating a utility that will survey printers to discover those experiencing a paper jam or other 
problem. 

Validate and Merge PrintTickets 

Instructions for checking that a print ticket is valid and that it does not request anything that is not supported by 
the printer. 

See also 

• System.Printing 

• System.Printing.IndexedProperties 

• System.Printing.Interop 

• Printing Overview 

• Documents in WPF 

• XPS Documents 




Howto: Invoke a Print Dialog 
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To provide the ability to print from you application, you can simply create and open a PrintDialog object. 

Example 

The PrintDialog control provides a single entry point for Ul, configuration, and XPS Job submission. The control is 
easy to use and can be instantiated by using Extensible Application Markup Language (XAML) markup or code. The 
following example demonstrates how to instantiate and open the control in code and how to print from it. It also 
shows how to ensure that the dialog will give the user the option of setting a specific range of pages. The example 
code assumes that there is a file FixedDocumentSequence.xps in the root of the C: drive. 

private void InvokePrint(object sendeCj RoutedEventArgs e) 

{ 

// Create the print dialog object and set options 
PrintDialog pDialog = new PrintDialogOj 
pDialog.PageRangeSelection = PageRangeSelection.AllPages; 
pDialog.UserPageRangeEnabled = truej 

// Display the dialog. This returns true if the user presses the Print button. 

Nullable<Boolean> print = pDialog.ShowDialogO; 
if (print == true) 

{ 

XpsDocument xpsDocument = new XpsDocument("C:\\FixedDocumentSequence.xps"j FileAccess.ReadWrite); 
FixedDocumentSequence fixedDocSeq = xpsDocument.GetFixedDocumentSequence(); 
pDialog.PrintDocument(fixedDocSeq.DocumentPaginatorj "Test print job"); 

} 

} 


Private Sub Invol<ePrint(ByVal sender As Object, ByVal e As RoutedEventArgs) 

' Create the print dialog object and set options 
Dim pDialog As New PrintDialog() 

pDialog.PageRangeSelection = PageRangeSelection.AllPages 
pDialog.UserPageRangeEnabled = True 

' Display the dialog. This returns true if the user presses the Print button. 

Dim print? As Boolean = pDialog.ShowDialogO 
If print = True Then 

Dim xpsDocument As New XpsDocument("C:\FixedDocumentSequence.xps", FileAccess.ReadWrite) 
Dim fixedDocSeq As FixedDocumentSequence = xpsDocument.GetFixedDocumentSequence() 
pDialog.PrintDocument(fixedDocSeq.DocumentPaginator, "Test print job") 

End If 

End Sub 


Once the dialog is open, users will be able to select from the printers installed on their computer. They will also 
have the option of selecting the Microsoft XPS Document Writer to create an XML Paper Specification (XPS) file 
instead of printing. 


NOTE 

The System.Windows.Controls.PrintDialog control of WPF, which is discussed in this topic, should not be confused with the 
System.Windows.Forms.PrintDialog component of Windows Forms. 






Strictly speaking, you can use the PrintDocument method without ever opening the dialog. In that sense, the 
control can be used as an unseen printing component. But for performance reasons, it would be better to use 
either the AddJob method or one of the many Write and WriteAsync methods of the XpsDocumentWriter. For 
more about this, see Programmatically Print XPS Files. 

See also 

• PrintDialog 

• Documents in WPF 

• Printing Overview 

• Microsoft XPS Document Writer 


How to: Clone a Printer 
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Most businesses will, at some point, buy multiple printers of the same model. Typically, these are all installed with 
virtually identical configuration settings. Installing each printer can be time-consuming and error prone. The 
System.Printing.IndexedProperties namespace and the InstallPrintQueue class that are exposed with Microsoft .NET 
Framework makes it possible to instantly install any number of additional print queues that are cloned from an 
existing print queue. 

Example 

In the example below, a second print queue is cloned from an existing print queue. The second differs from the first 
only in its name, location, port, and shared status. The major steps for doing this are as follows. 

1. Create a PrintQueue object for the existing printer that is going to be cloned. 

2. Create a PrintPropertyDictionary from the PropertiesCollection of the PrintQueue. The Value property of 
each entry in this dictionary is an object of one of the types derived from PrintProperty. There are two ways 
to set the value of an entry in this dictionary. 

• Use the dictionary's Remove and Add methods to remove the entry and then re-add it with the 
desired value. 

• Use the dictionary's SetProperty method. 

The example below illustrates both ways. 

3. Create a PrintBooleanProperty object and set its Name to "IsShared" and its Value to true . 

4. Use the PrintBooleanProperty object to be the value of the PrintPropertyDictionary's "IsShared" entry. 

5. Create a PrintStringProperty object and set its Name to "ShareName" and its Value to an appropriate String. 

6. Use the PrintStringProperty object to be the value of the PrintPropertyDictionary's "ShareName" entry. 

7. Create another PrintStringProperty object and set its Name to "Location" and its Value to an appropriate 
String. 

8. Use the second PrintStringProperty object to be the value of the PrintPropertyDictionary's "Location" entry. 

9. Create an array of Strings. Each item is the name of a port on the server. 

10. Use InstallPrintQueue to install the new printer with the new values. 


An example is below. 





LocalPrintServen myLocalPrintSenver = new LocalPnintServer(PnintSystemDesiredAccess.AdministrateServer); 
PrintQueue sourcePrintQueue = myLocalPrintServen.DefaultPrintQueuej 
PrintPropertyDictionary myPrintProperties = sourcePrintQueue.PropertiesCollection; 

// Share the new printer using Remove/Add methods 

PrintBooleanProperty shared = new PrintBooleanPropertyC'IsShared", true)j 
myPrintProperties.Remove("IsShared"); 
myPrintProperties.Add("IsShared"^ shared); 

// Give the new printer its share name using SetProperty method 

PrintStringProperty theShareName = new PrintStringProperty("ShareName"j "\"Son of " + sourcePrintQueue.Name 
myPrintProperties.SetProperty("ShareName"j theShareName); 

// Specify the physical location of the new printer using Remove/Add methods 
PrintStringProperty theLocation = new PrintStringProperty("Location"j "the supply room")j 
myPrintProperties.Remove("Location"); 
myPrintProperties.Add("Location"j theLocation); 

// Specify the port for the new printer 
String[] port = new String[] { "COMl:" }; 

// Install the new printer on the local print server 

PrintQueue clonedPrinter = myLocalPrintSenver.InstallPrintQueue("My clone of " + sourcePrintQueue.Name^ "Xerox 
WCP 35 PS", port, "WinPrint", myPrintProperties); 
myLocalPrintServer.Commit(); 

// Report outcome 

Console.WriteLine("{0} in {1} has been installed and shared as {2}", clonedPrinter.Name, 
clonedPrinter.Location, clonedPrinter.ShareName); 

Console.WriteLine("Press Return to continue ..."); 

Console.ReadLlneO; 


Dim myLocalPrintSenver As New LocalPrlntServer(PrintSystemDesiredAccess.AdministrateServer) 

Dim sourcePrintQueue As PrintQueue = myLocalPrintSenver.DefaultPrintQueue 

Dim myPrintProperties As PrintPropertyDictionary = sourcePrintQueue.PropertiesCollection 

' Share the new printer using Remove/Add methods 
Dim [shared] As New PrintBooleanPropertyC'IsShared", True) 
myPrintProperties.Remove("IsShared") 
myPrintProperties.Add("IsShared", [shared]) 

' Give the new printer its share name using SetProperty method 

Dim theShareName As New PrintStringPropertyC'ShareName", """Son of " & sourcePrintQueue.Name & .) 

myPrintProperties.SetProperty("ShareName", theShareName) 

' Specify the physical location of the new printer using Remove/Add methods 
Dim theLocation As New PrintStringPropertyC'Location", "the supply room") 
myPrintProperties.Remove("Location") 
myPrintProperties.Add("Location", theLocation) 

' Specify the port for the new printer 
Dim port() As String = { "COMl:" } 

' Install the new printer on the local print server 

Dim clonedPrinter As PrintQueue = myLocalPrintServer.InstallPrintQueue("My clone of " & sourcePrintQueue.Name, 
"Xerox WCP 35 PS", port, "WinPrint", myPrintProperties) 
myLocalPrintServer.Commit() 

' Report outcome 

Console.WriteLine("{0} in {1} has been installed and shared as {2}", clonedPrinter.Name, 
clonedPrinter.Location, clonedPrinter.ShareName) 

Console.WriteLine("Press Return to continue ...") 

Console.ReadLlneO 




See also 

• System.Printing.IndexedProperties 

• PrintPropertyDictionary 

• LocalPrintServer 

• PrintQueue 

• DictionaryEntry 

• Documents in WPF 

• Printing Overview 


How to: Diagnose Problematic Print Job 

3/12/2020 • 15 minutes to read ^ Edit Online 


Network administrators often field complaints from users about print jobs that do not print or print slowly. The rich 
set of print job properties exposed in the APIs of Microsoft .NET Framework provide a means for performing a 
rapid remote diagnosis of print jobs. 

Example 

The major steps for creating this kind of utility are as follows. 

1. Identify the print job that the user is complaining about. Users often cannot do this precisely. They may not 
know the names of the print servers or printers. They may describe the location of the printer in different 
terminology than was used in setting its Location property. Accordingly, it is a good idea to generate a list of 
the user's currently submitted jobs. If there is more than one, then communication between the user and the 
print system administrator can be used to pinpoint the job that is having problems. The substeps are as 
follows. 

a. Obtain a list of all print servers. 

b. Loop through the servers to query their print queues. 

c. Within each pass of the server loop, loop through all the server's queues to query their jobs 

d. Within each pass of the queue loop, loop through its jobs and gather identifying information about 
those that were submitted by the complaining user. 

2. When the problematic print job has been identified, examine relevant properties to see what might be the 
problem. For example, is job in an error state or did the printer servicing the queue go offline before the job 
could print? 

The code below is series of code examples. The first code example contains the loop through the print queues. (Step 
1 c above.) The variable myPnintQueues is the PrintQueueCollection object for the current print server. 

The code example begins by refreshing the current print queue object with PrintQueue.Refresh. This ensures that 
the object's properties accurately represent the state of the physical printer that it represents. Then the application 
gets the collection of print jobs currently in the print queue by using GetPrinLlobInfoCollection. 

Next the application loops through the PrintSystemJobInfo collection and compares each Submitter property with 
the alias of the complaining user. If they match, the application adds identifying information about the job to the 
string that will be presented. (The usenName and jobiist variables are initialized earlier in the application.) 







for each (PrintQueue'' pq in myPrintQueues) 

{ 

pq->Refresh(); 

PrintDobInfoCollection'' jobs = pq->GetPrint]obInfoCollection(); 
for each (PrintSystemiobInfo'' job in jobs) 

{ 

// Since the user may not be able to articulate which job is problematiCj 
// present information about each job the user has submitted, 
if (job->Submitter == userName) 

{ 

atLeastOne = true; 

jobList = jobList + "\nServer:" + line; 
jobList = jobList + "\n\tQueue:" + pq->Name; 
jobList = jobList + "\n\tLocation:" + pq->Location; 

jobList = jobList + "\n\t\t3ob: " + job->]obName + " ID: " + job->]obIdentifier; 

} 

} 

} 


foreach (PrintQueue pq in myPrintQueues) 

{ 

pq.RefreshO; 

PrintlobInfoCollection jobs = pq.GetPrintlobInfoCollectionO; 
foreach (PrintSystemlobInfo job in jobs) 

{ 

// Since the user may not be able to articulate which job is problematiCj 
// present information about each job the user has submitted, 
if (job.Submitter == userName) 

{ 

atLeastOne = true; 

jobList = jobList + "\nServer:" + line; 
jobList = jobList + "\n\tQueue:" + pq.Name; 
jobList = jobList + "\n\tLocation:" + pq.Location; 

jobList = jobList + "\n\t\tIob: " + job.IobName + " ID: " + job.Iobldentifier; 

} 

}// end for each print job 
}// end for each print queue 


For Each pq As PrintQueue In myPrintQueues 
pq.RefreshO 

Dim jobs As PrintlobInfoCollection = pq.GetPrint]obInfoCollection() 

For Each job As PrintSystemlobInfo In jobs 

' Since the user may not be able to articulate which job is problematic^ 

' present information about each job tbe user bas submitted. 

If job.Submitter = userName Then 
atLeastOne = True 

jobList = jobList & vbLf & "Server:" & line 

jobList = jobList & vbLf & vbTab & "Queue:" & pq.Name 

jobList = jobList & vbLf & vbTab & "Location:" & pq.Location 

jobList = jobList & vbLf & vbTab & vbTab & "lob: " & job.IobName & " ID: " & job.Iobldentifier 

End If 

Next job ' end for each print job 
Next pq ' end for each print queue 


The next code example picks up the application at Step 2. (See above.) The problematic job has been identified and 
the application prompts for the information that will identify it. From this information it creates PrintServer, 
PrintQueue, and PrintSystemJobInfo objects. 

At this point the application contains a branching structure corresponding to the two ways of checking a print job's 


status: 



• You can read the flags of the JobStatus property which is of type PrintJobStatus. 


• You can read each relevant property such as IsBIocked and IsInError. 

This example demonstrates both methods, so the user was previously prompted as to which method to use and 
responded with "Y" if they wanted to use the flags of the JobStatus property. See below for the details of the two 
methods. Finally, the application uses a method called ReportQueueAndJobAvailability to report on whether 
the job can be printed at this time of day. This method is discussed in Discover Whether a Print Job Can Be Printed 
At This Time of Day. 

// When the problematic print job has been identified, enter information about it. 

Console::Write("\nEnter the print server hosting the job (including leading slashes \\\\): " + "\n(press 
Return for the current computer \\\\{0}): ", Environment::MachineName)j 
string'' pServer = Console: :ReadLine(); 
if (pServer == "") 

{ 

pServer = "\\\\" + Environment::MachineNamej 

} 

Console::Write("\nEnter the print queue hosting the job: "); 

String'' pQueue = Console: :ReadLine(); 

Console::Write("\nEnter the job ID: "); 

Intis jobID = Convert::ToIntl6(Console::ReadLine()); 

// Create objects to represent the server, queue, and print job. 

PrintServer'' hostingServer = gcnew PrintServer(pServer, PrintSystemDesiredAccess::AdministrateServer); 
PrintQueue^ hostingQueue = gcnew PrintQueue(hostingServer, pQueue, 

PrintSystemDesiredAccess::AdministratePrinter)j 
PrintSystemloblnfo'' thelob = hostingQueue->Get]ob(jobID); 

if (useAttributesResponse == "Y") 

{ 

TroubleSpotter::SpotTroubleUsingIobAttributes(the]ob); 

// TroubleSpotter class is defined in the complete example. 

} else 

{ 

TroubleSpotter::SpotTroubleUsingProperties(the]ob); 

} 

T roubleSpotter::ReportQueueAndlobAvailability(thelob); 



// when the problematic print job has been identified, enter information about it. 

Console.Write("\nEnter the print server hosting the job (including leading slashes \\\\): " + 

"\n(press Return for the current computer \\\\{0}): ", Environment.MachineName); 

String pServer = Console.ReadLine(); 
if (pServer == "") 

{ 

pServer = "\\\\" +Environment.MachineName; 

} 

Console.Write("\nEnter the print queue hosting the job: "); 

String pQueue = Console.ReadLine(); 

Console.Write("\nEnter the job ID: "); 

Intis jobID = Convert.ToIntl6(Console.ReadLine()); 

// Create objects to represent the server, queue, and print job. 

PrintServer hostingServer = new PrintServer(pServer, PrintSystemDesiredAccess.AdministrateServer); 

PrintQueue hostingQueue = new PrintQueue(hostingServer, pQueue, PrintSystemDesiredAccess.AdministratePrinter); 
PrintSystemlobInfo thelob = hostingQueue.Get]ob(jobID); 

if (useAttributesResponse == "Y") 

{ 

TroubleSpotter.SpotTroubleLlsinglobAttributes(the]ob); 

// TroubleSpotter class is defined in the complete example. 

} 

else 

{ 

TroubleSpotter.SpotTroubleUsingProperties(the]ob); 

} 

TroubleSpotter.ReportQueueAnd3obAvailability(the]ob); 


' When the problematic print job has been identified, enter information about it. 

Console.Write(vbLf & "Enter the print server hosting the job (including leading slashes \\): " & vbLf & 
(press Return for the current computer \\{0}): ", Environment.MachineName) 

Dim pServer As String = Console.ReadLine() 

If pServer = "" Then 

pServer = "\\" & Environment.MachineName 
End If 

Console.Write(vbLf & "Enter the print queue hosting the job: ") 

Dim pQueue As String = Console.ReadLine() 

Console.Write(vbLf & "Enter the job ID: ") 

Dim jobID As Intl6 = Convert.ToIntl6(Console.ReadLine()) 

' Create objects to represent the server, queue, and print job. 

Dim hostingServer As New PrintServer(pServer, PrintSystemDesiredAccess.AdministrateServer) 

Dim hostingQueue As New PrintQueue(hostingServer, pQueue, PrintSystemDesiredAccess.AdministratePrinter) 
Dim thelob As PrintSystemlobInfo = hostingQueue.GetIob(jobID) 

If useAttributesResponse = "Y" Then 

TroubleSpotter. SpotTroubleLlsing]obAttributes(the]ob) 

' TroubleSpotter class is defined in the complete example. 

Else 

TroubleSpotter.SpotTroubleUsingProperties(thelob) 

End If 

TroubleSpotter.ReportQueueAnd3obAvailability(the]ob) 


To check print job status using the flags of the JobStatus property, you check each relevant flag to see if it is set. The 
standard way to see if one bit is set in a set of bit flags is to perform a logical AND operation with the set of flags as 
one operand and the flag itself as the other. Since the flag itself has only one bit set, the result of the logical AND is 
that, at most, that same bit is set. To find out whether it is or not. Just compare the result of the logical AND with the 
flag itself For more information, see PrinLlobStatus, the & Operator (C# Reference), and FlagsAttribute. 

For each attribute whose bit is set, the code reports this to the console screen and sometimes suggests a way to 



respond. (The HandlePausedJob method that is called if the job or queue is paused is discussed below.) 

// Check for possible trouble states of a print job using the flags of the lobStatus property 
static void SpotTroubleUsinglobAttributes (PrintSystemlobInfo'' tbelob) 

{ 

if ((theDob->lobStatus & PrintlobStatus::Blocked) == PrintlobStatus::Blocked) 

{ 

Console::WriteLine("The job is blocked."); 

} 

if (((thelob->3obStatus & PrintlobStatus;rCompleted) == PrintlobStatus:rCompleted) 

II 

((theIlob->]obStatus & PrintlobStatus::Printed) == PrintlobStatus::Printed)) 

{ 

Console::WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked."); 

} 

if (((the]ob->3obStatus & PrintlobStatus::Deleted) == PrintlobStatus::Deleted) 

II 

((the]ob->lobStatus & PrintlobStatus::Deleting) == PrintlobStatus::Deleting)) 

{ 

Console::WriteLine("The user or someone with administration rights to the queue has deleted the job. It 
must be resubmitted."); 

} 

if ((the]ob->IobStatus & PrintlobStatus::Error) == PrintlobStatus::Error) 

{ 

Console::WriteLine("The job bas errored."); 

} 

if ((the]ob->IobStatus & PrintlobStatus::Offline) == PrintlobStatus::Offline) 

{ 

Console::WriteLine("The printer is offline. Have user put it online with printer front panel."); 

} 

if ((the]ob->IobStatus & PrintlobStatus::PaperOut) == PrintlobStatus::PaperOut) 

{ 

Console: :WriteLine("The printer is out of paper of the size required by the job. Have user add paper.") 

} 

if (((theIob->3obStatus & PrintlobStatus::Paused) == PrintlobStatus::Paused) 

II 

((theIlob->HostingPrintQueue->QueueStatus & PrintQueueStatus::Paused) == PrintQueueStatus::Paused)) 

{ 

HandlePaused]ob(the3ob); 

//HandlePausedlob is defined in the complete example. 

} 

if ((theIob->IobStatus & PrintlobStatus::Printing) == PrintlobStatus::Printing) 

{ 

Console::WriteLine("The job is printing now."); 

} 

if ((theIob->IobStatus & PrintlobStatus::Spooling) == PrintlobStatus::Spooling) 

{ 

Console::WriteLine("The job is spooling now."); 

} 

if ((the]ob->IobStatus & PrintlobStatus::UserIntervention) == PrintlobStatus::LlserIntervention) 

{ 

Console::WriteLine("The printer needs human intervention."); 


} 



// Check for possible trouble states of a print job using the flags of the lobStatus property 
internal static void SpotTroubleUsing3obAttributes(PrintSystem]obInfo thelob) 

{ 

if ((thelob.lobStatus & PrintlobStatus.Blocked) == PrintlobStatus.Blocked) 

{ 

Console.WriteLine("The job is blocked."); 

} 

if (((thelob.lobStatus & PrintlobStatus.Completed) == PrintlobStatus.Completed) 

II 

((thelob.lobStatus & PrintlobStatus.Printed) == PrintlobStatus.Printed)) 

{ 

Console.WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked."); 

} 

if (((thelob.lobStatus & PrintlobStatus.Deleted) == PrintlobStatus.Deleted) 

II 

((thelob.DobStatus & PrintlobStatus.Deleting) == PrintlobStatus.Deleting)) 

{ 

Console.WriteLine("The user or someone with administration rights to the queue has deleted the job. 
must be resubmitted."); 

} 

if ((thelob.lobStatus & PrintlobStatus.Error) == PrintlobStatus.Error) 

{ 

Console.WriteLine("The job has errored."); 

} 

if ((thelob.lobStatus & PrintlobStatus.Offline) == PrintlobStatus.Offline) 

{ 

Console.WriteLine("The printer is offline. Have user put it online with printer front panel."); 

} 

if ((thelob.lobStatus & PrintDobStatus.PaperOut) == PrintlobStatus.PaperOut) 

{ 

Console.WriteLine("The printer is out of paper of the size required by the job. Have user add 
paper."); 

} 

if (((thelob.lobStatus & PrintlobStatus.Paused) == PrintlobStatus.Paused) 

II 

((thelob.HostingPrintQueue.QueueStatus & PrintQueueStatus.Paused) == PrintQueueStatus.Paused)) 

{ 

HandlePaused]ob(the]ob); 

//HandlePausedlob is defined in the complete example. 

} 

if ((thelob.lobStatus & PrintlobStatus.Printing) == PrintlobStatus.Printing) 

{ 

Console.WriteLine("The job is printing now."); 

} 

if ((thelob.lobStatus & PrintlobStatus.Spooling) == PrintlobStatus.Spooling) 

{ 

Console.WriteLine("The job is spooling now."); 

} 

if ((thelob.lobStatus & PrintlobStatus.Userlntervention) == PrintlobStatus.Userlntervention) 

{ 

Console.WriteLine("The printer needs human intervention."); 

} 

}//end SpotTroubleUsinglobAttributes 



' Check for possible trouble states of a print job using the flags of the lobStatus property 
Friend Shared Sub SpotTroubleUsing]obAttributes(ByVal thelob As PrintSystemlobInfo) 

If (thelob.lobStatus And PrintlobStatus.Blocked) = PrintlobStatus.Blocked Then 
Console.WriteLine("The job is blocked.") 

End If 

If ((thelob.IobStatus And PrintlobStatus.Completed) = PrintlobStatus.Completed) OrElse ((thelob.lobStatus 
And PrintlobStatus.Printed) = PrintlobStatus.Printed) Then 

Console.WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked.") 

End If 

If ((thelob.IobStatus And PrintlobStatus.Deleted) = PrintlobStatus.Deleted) OrElse ((thelob.lobStatus And 
PrintlobStatus.Deleting) = PrintlobStatus.Deleting) Then 

Console.WriteLine("The user or someone with administration rights to the queue has deleted the job. It 
must be resubmitted.") 

End If 

If (thelob.IobStatus And PrintlobStatus.Error) = PrintlobStatus.Error Then 
Console.WriteLine("The job has errored.") 

End If 

If (thelob.IobStatus And PrintlobStatus.Offline) = PrintlobStatus.Offline Then 

Console.WriteLine("The printer is offline. Have user put it online with printer front panel.") 

End If 

If (thelob.IobStatus And PrintlobStatus.PaperOut) = PrintlobStatus.PaperOut Then 

Console.WriteLine("The printer is out of paper of the size required by the job. Have user add paper.") 
End If 

If ((thelob.IobStatus And PrintlobStatus.Paused) = PrintlobStatus.Paused) OrElse 
((thelob.HostingPrintQueue.QueueStatus And PrintQueueStatus.Paused) = PrintQueueStatus.Paused) Then 
HandlePausedlob(thelob) 

'HandlePausedlob is defined in the complete example. 

End If 

If (thelob.IobStatus And PrintlobStatus.Printing) = PrintlobStatus.Printing Then 
Console.WriteLine("The job is printing now.") 

End If 

If (thelob.IobStatus And PrintlobStatus.Spooling) = PrintlobStatus.Spooling Then 
Console.WriteLine("The job is spooling now.") 

End If 

If (thelob.IobStatus And PrintlobStatus.Userintervention) = PrintlobStatus.Userintervention Then 
Console.WriteLine("The printer needs human intervention.") 

End If 

End Sub 

To check print job status using separate properties, you simply read each property and, if the property is true , 
report to the console screen and possibly suggest a way to respond. (The HandlePausedJob method that is called 
if the job or queue is paused is discussed below.) 




// Check for possible trouble states of a print job using its properties 
static void SpotTroubleUsingProperties (PrintSystemlobInfo'' thelob) 

{ 

if (the]ob->IsBlocked) 

{ 

Console::WriteLine("The job is blocked."); 

} 

if (the]ob->IsCompleted || the3ob->IsPrinted) 

{ 

Console::WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked."); 

} 

if (the]ob->IsDeleted | | theIlob->IsDeleting) 

{ 

Console::WriteLine("The user or someone with administration rights to the queue has deleted the job. It 
must be resubmitted."); 

} 

if (the]ob->IsInError) 

{ 

Console::WriteLine("The job has errored."); 

} 

if (the]ob->IsOffline) 

{ 

Console::WriteLine("The printer is offline. Have user put it online with printer front panel."); 

} 

if (the]ob->IsPaperOut) 

{ 

Console::WriteLine("The printer is out of paper of the size required by the job. Have user add paper.") 

} 

if (the]ob->IsPaused || theIob->HostingPrintQueue->IsPaused) 

{ 

HandlePaused]ob(the3ob); 

//HandlePausedlob is defined in the complete example. 

} 

if (theIob->IsPrinting) 

{ 

Console::WriteLine("The job is printing now."); 

} 

if (the]ob->IsSpooling) 

{ 

Console::WriteLine("The job is spooling now."); 

} 

if (theIob->IsUserInterventionRequired) 

{ 

Console::WriteLine("The printer needs human intervention."); 


} 



// Check for possible trouble states of a print job using its properties 
internal static void SpotTroubleUsingProperties(PrintSystemlobInfo thelob) 

{ 

if (theDob.IsBlocked) 

{ 

Console.WriteLine("The job is blocked."); 

} 

if (thelob.IsCompleted || thelob.IsPrinted) 

{ 

Console.WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked."); 

} 

if (theDob.IsDeleted || theDob.IsDeleting) 

{ 

Console.WriteLine("The user or someone with administration rights to the queue has deleted the job. 
must be resubmitted."); 

} 

if (theDob.IsInError) 

{ 

Console.WriteLine("The job has errored."); 

} 

if (theDob.IsOffline) 

{ 

Console.WriteLine("The printer is offline. Have user put it online with printer front panel."); 

} 

if (theDob.IsPaperOut) 

{ 

Console.WriteLine("The printer is out of paper of the size required by the job. Have user add 
paper."); 

} 

if (theDob.IsPaused || theDob.HostingPrintQueue.IsPaused) 

{ 

HandlePausedDob(theDob); 

//HandlePausedDob is defined in the complete example. 

} 

if (theDob.IsPrinting) 

{ 

Console.WriteLine("The job is printing now."); 

} 

if (theDob.IsSpooling) 

{ 

Console.WriteLine("The job is spooling now."); 

} 

if (theDob.IsUserInterventionRequired) 

{ 

Console.WriteLine("The printer needs human intervention."); 

} 

}//end SpotTroubleUsingProperties 



' Check for possible trouble states of a print job using its properties 
Friend Shared Sub SpotTroubleUsingProperties(ByVal thelob As PrintSystemlobInfo) 
If thelob.IsBlocked Then 

Console.WriteLine("The job is blocked.") 

End If 


If thelob.IsCompleted OrElse thelob.IsPrinted Then 

Console.WriteLine("The job has finished. Have user recheck all output bins and be sure the correct 
printer is being checked.") 

End If 

If thelob.IsDeleted OrElse thelob.IsDeleting Then 

Console.WriteLine("The user or someone with administration rights to the queue has deleted the job. It 
must be resubmitted.") 

End If 


If thelob.IsInError Then 

Console.WriteLine("The job has errored.") 

End If 

If thelob.IsOffline Then 

Console.WriteLine("The printer is offline. Have user put it online with printer front panel.") 

End If 

If thelob.IsPaperOut Then 

Console.WriteLine("The printer is out of paper of the size required by the job. Have user add paper.") 
End If 


If thelob.IsPaused OrElse thelob.HostingPrintQueue.IsPaused Then 
HandlePausedIob(the]ob) 

'HandlePausedTob is defined in the complete example. 

End If 


If thelob.IsPrinting Then 

Console.WriteLine("The job is printing now.") 

End If 

If thelob.IsSpooling Then 

Console.WriteLine("The job is spooling now.") 

End If 

If thelob.IsUserInterventionRequired Then 

Console.WriteLine("The printer needs human intervention.") 
End If 

End Sub 


The HandlePausedJob method enables the application's user to remotely resume paused jobs. Because there 
might be a good reason why the print queue was paused, the method begins by prompting for a user decision 
about whether to resume it. If the answer is "Y", then the PrintQueue.Resume method is called. 

Next the user is prompted to decide if thejob itself should be resumed, just in case it is paused independently of 
the print queue. (Compare PrintQueue.lsPaused and PrintSystemJobInfo.lsPaused.) If the answer is "Y", then 
PrintSystemJobInfo.Resume is called; otherwise Cancel is called. 



static void HandlePausediob (PrintSystemiobInfo'' theiob) 

{ 

// If there's no good reason for the queue to be paused^ resume it and 
// give user choice to resume or cancel the job. 

Console::WriteLine("The user or someone with administrative rights to the queue" + "\nhas paused the job or 
queue." + "\nResume the queue? (Has no effect if queue is not paused.)" + "\nEnter \"Y\" to resumOj otherwise 
press return: "); 

String'' resume = Console: :ReadLine(); 
if (resume == "Y") 

{ 

the3ob->HostingPrintQueue->Resume(); 

// It is possible the job is also paused. Find out how the user wants to handle that. 

Console::WriteLine("Does user want to resume print job or cancel it?" + "\nEnter \"Y\" to resume (any 
other key cancels the print job): "); 

String'' userDecision = Console: :ReadLine()j 
if (userDecision == "Y") 

{ 

the]ob->Resume(); 

} else 

{ 

the]ob->Cancel(); 

} 

} 

}; 


internal static void HandlePausedIob(PrintSystem]obInfo thelob) 

{ 

// If there's no good reason for the queue to be paused, resume it and 
// give user choice to resume or cancel the job. 

Console.WriteLine("The user or someone with administrative rights to the queue" + 

"\nhas paused the job or queue." + 

"\nResume the queue? (Has no effect if queue is not paused.)" + 

"\nEnter \"Y\" to resume, otherwise press return: "); 

String resume = Console.ReadLine(); 
if (resume == "Y") 

{ 

thelob.HostingPrintQueue.Resume(); 

// It is possible the job is also paused. Find out how the user wants to handle that. 
Console.WriteLine("Does user want to resume print job or cancel it?" + 

"\nEnter \"Y\" to resume (any other key cancels the print job): ")j 
String userDecision = Console.ReadLine(); 
if (userDecision == "Y") 

{ 

thelob.Resume(); 

} 

else 

{ 

thelob.CancelO; 

} 

}//end if the queue should be resumed 
}//end HandlePausedlob 



Friend Shared Sub HandlePausedDob(By\/al theiob As PrintSystemDobInfo) 

' If there's no good reason for the queue to be pausedj resume it and 
' give user choice to resume or cancel the job. 

Console.WriteLine("The user or someone with administrative rights to the queue" & vbLf & 
job or queue." & vbLf & "Resume the queue? (Has no effect if queue is not paused.)" & vbLf & 
resume, otherwise press return: ") 

Dim [resume] As String = Console.ReadLine() 

If [resume] = "Y" Then 

theIlob.HostingPrintQueue.Resume() 

' It is possible the job is also paused. Find out how the user wants to handle that. 
Console.WriteLine("Does user want to resume print job or cancel it?" & vbLf & "Enter 
(any other key cancels the print job): ") 

Dim userDecision As String = Console.ReadLine() 

If userDecision = "Y" Then 
thelob.Resume() 

Else 

thelob.CancelO 
End If 

End If 'end if the queue should be resumed 
End Sub 


See also 

• PrinUobStatus 

• PrintSystemJobInfo 

• FlagsAttribute 

• PrintQueue 

• 8t Operator (C# Reference) 

• Documents in WPF 

• Printing Overview 
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How to: Discover Whether a Print Job Can Be 
Printed At This Time of Day 

8/22/2019 • 8 minutes to read i Edit Online 


Print queues are not always available for 24 hours a day. They have start and end time properties that can be set to 
make them unavailable at certain times of day. This feature can be used, for example, to reserve a printer for the 
exclusive use of a certain department after 5 P.M.. That department would have a different queue servicing the 
printer than other departments use. The queue for the other departments would be set to be unavailable after 5 
P.M., while queue for the favored department could be set to be available at all times. 

Moreover, print jobs themselves can be set to be printable only within a specified span of time. 

The PrintQueue and PrintSystemJobInfo classes exposed in the APIs of Microsoft .NET Framework provide a means 
for remotely checking whether a given print job can print on a given queue at the current time. 

Example 

The example below is a sample that can diagnose problems with a print job. 

There are two major steps for this kind of function as follows. 

1. Read the StartTimeOfDay and UntilTimeOfDay properties of the PrintQueue to determine whether the 
current time is between them. 

2. Read the StartTimeOfDay and UntilTimeOfDay properties of the PrintSystemJobInfo to determine whether 
the current time is between them. 

But complications arise from the fact that these properties are not DateTime objects. Instead they are Int32 objects 
that express the time of day as the number of minutes since midnight. Moreover, this is not midnight in the current 
time zone, but midnight UTC (Coordinated Universal Time). 

The first code example presents the static method ReportQueueAndJobAvailability, which is passed a 
PrintSystemJobInfo and calls helper methods to determine whether the job can print at the current time and, if not, 
when it can print. Notice that a PrintQueue is not passed to the method. This is because the PrintSystemJobInfo 
includes a reference to the queue in its HostingPrintQueue property. 

The subordinate methods include the overloaded ReportAvailabilityAtThisTime method which can take either a 
PrintQueue or a PrintSystemJobInfo as a parameter. There is also a 

TimeConverter.ConvertToLocaIHumanReadableTime. All of these methods are discussed below. 

The ReportQueueAndJobAvailability method begins by checking to see if either the queue or the print job is 
unavailable at this time. If either of them is unavailable, it then checks to see if the queue unavailable. If it is not 
available, then the method reports this fact and the time when the queue will become available again. It then 
checks the job and if it is unavailable, it reports the next time span when it when it can print. Finally, the method 
reports the earliest time when the job can print. This is the later of following two times. 

• The time when the print queue is next available. 

• The time when the print job is next available. 

When reporting times of day, the ToShortTimeString method is also called because this method suppresses the 
years, months, and days from the output. You cannot restrict the availability of either a print queue or a print job to 
particular years, months, or days. 




static void ReportQueueAndiobAvailability (PrintSystemiobInfo'' theiob) 

{ 

if (!(ReportAvailabilityAtThisTime(the]ob->HostingPrintQueue) && ReportAvailabilityAtThisTime(the3ob))) 

{ 

if (!ReportAvailabilityAtThisTime(the]ob->HostingPrintQueue)) 

{ 

Console::WriteLine("\nThat queue is not available at this time of day." + "\nlobs in the queue will 
start printing again at {0}", TlmeConverter::ConvertToLocalHumanReadableTime(thelob->HostingPrintQueue- 
>StartTimeOfDay) .ToShortTimeStringO); 

// TimeConverter class is defined in the complete sample 

} 

if (!ReportAvailabilityAtThisTime(thelob)) 

{ 

Console::WriteLine("\nThat job is set to print only between {0} and {1}", 

TimeConverter::ConvertToLocalHumanReadableTime(the]ob->StartTimeOfDay).ToShortTimeStringOj 
TimeConverter::ConvertToLocalHumanReadableTime(the]ob->UntilTimeOfDay).ToShortTimeStringO); 

} 

Console::WriteLine("\nThe job will begin printing as soon as it reaches the top of the queue after:"); 
if (theIlob->StartTimeOfDay > the]ob->HostingPrintQueue->StartTimeOfDay) 

{ 

Console::WriteLine(TimeConverter::ConvertToLocalHumanReadableTime(the]ob- 
>StartTimeOfDay) .ToShortTimeStringO); 

} else 

{ 

Console::WriteLine(TimeConverter::ConvertToLocalHumanReadableTime(the]ob->HostingPrintQueue- 
>StartTimeOfDay) .ToShortTimeStringO); 

} 

} 

}; 


internal static void ReportQueueAndTobAvailability(PrintSystem]obInfo thelob) 

{ 

if (!(ReportAvailabilityAtThisTime(thelob.HostingPrintQueue) && ReportAvailabilityAtThisTime(the3ob))) 

{ 

if (!ReportAvailabilityAtThisTime(thelob.HostingPrintQueue)) 

{ 

Console.WriteLine("\nThat queue is not available at this time of day." + 

"\nDobs in the queue will start printing again at { 0 }", 

TimeConverter.ConvertToLocalHumanReadableTime(thelob.HostingPrintQueue.StartTimeOfDay).ToShortTimeStringO); 

// TimeConverter class is defined in the complete sample 

} 

if (!ReportAvailabilityAtThisTime(thelob)) 

{ 

Console.WriteLine("\nThat job is set to print only between {0} and {1}", 

TimeConverter.ConvertToLocalHumanReadableTime(thelob.StartTimeOfDay).ToShortTimeStringOj 
TimeConverter.ConvertToLocalHumanReadableTime(thelob.LlntilTimeOfDay) .ToShortTimeStringO); 

} 

Console.WriteLine("\nThe job will begin printing as soon as it reaches the top of the queue after:"); 
if (thelob.StartTimeOfDay > theDob.HostingPrintQueue.StartTimeOfDay) 

{ 

Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(the]ob.StartTimeOfDay).ToShortTimeStringO); 

} 

else 

{ 

Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(the]ob.HostingPrintQueue.StartTimeOfDay).ToSho 
rtTimeStringO); 

} 

}//end if at least one is not available 
}//end ReportQueueAndlobAvailability 



Friend Shared Sub ReportQueueAnd]obAvailability(ByVal theiob As PrintSystemDobInfo) 

If Not(ReportAvailabilityAtThisTime(thelob.HostingPrintQueue) AndAlso 
ReportAvailabilltyAtThisTime(thelob)) Then 

If Not ReportAvailabilityAtThisTime(thelob.HostingPrintQueue) Then 

Console.WriteLine(vbLf & "That queue is not available at this time of day." & vbLf & "Dobs in the 
queue will start printing again at {0}"j 

TimeConverter.ConvertToLocalHumanReadableTime(theDob.HostingPrintQueue.StartTimeOfDay).ToShortTimeStringO) 

' TimeConverter class is defined in the complete sample 
End If 

If Not ReportAvailabilityAtThisTime(theDob) Then 

Console.WriteLine(vbLf & "That job is set to print only between {0} and {l}"j 
TimeConverter.ConvertToLocalHumanReadableTime(theDob.StartTimeOfDay).ToShortTimeStringOj 
TimeConverter.ConvertToLocalHumanReadableTime(theDob.UntilTimeOfDay) .ToShortTimeStringO) 

End If 

Console.WriteLine(vbLf & "The job will begin printing as soon as it reaches the top of the queue 

after:") 

If theDob.StartTimeOfDay > theDob.HostingPrintQueue.StartTimeOfDay Then 

Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(theDob.StartTimeOfDay).ToShortTimeStringO) 
Else 

Console.WriteLine(TimeConverter.ConvertToLocalHumanReadableTime(theDob.HostingPrintQueue.StartTimeOfDay).ToSho 
rtTimeStringO) 

End If 

End If 'end if at least one is not available 

End Sub 


The two overloads of the ReportAvailabilityAtThisTime method are identical except for the type passed to 
them, so only the PrintQueue version is presented below. 


NOTE 

The fact that the methods are identical except for type raises the question of why the sample does not create a generic 
method ReportAvailabilityAtThisTime<T>. The reason is that such a method would have to be restricted to a class that 
has the StartTimeOfDay and UntilTimeOfDay properties that the method calls, but a generic method can only be 
restricted to a single class and the only class common to both PrintQueue and PrintSystemJobInfo in the inheritance tree is 
PrintSystemObject which has no such properties. 


The ReportAvailabilityAtThisTime method (presented in the code example below) begins by initializing a 
Boolean sentinel variable to true . It will be reset to false , if the queue is not available. 

Next, the method checks to see if the start and "until" times are identical. If they are, the queue is always available, 
so the method returns true . 

If the queue is not available all the time, the method uses the static UtcNow property to get the current time as a 
DateTime object. (We do not need local time because the StartTimeOfDay and UntilTimeOfDay properties are 
themselves in UTC time.) 

However, these two properties are not DateTime objects. They are Int32s expressing the time as the number of 
minutes-after-UTC-midnight. So we do have to convert our DateTime object to minutes-after-midnight. When that 
is done, the method simply checks to see whether "now" is between the queue's start and "until" times, sets the 
sentinel to false if "now" is not between the two times, and returns the sentinel. 







static Boolean ReportAvailabilityAtThisTime (PnintQueue'' pq) 

{ 

Boolean available = true; 

if (pq->StartTimeOfDay != pq->UntilTimeOfDay) 

{ 

DateTime utcNow = DateTime::UtcNow; 

Int32 utcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + utcNow.TimeOfDay.Minutes; 

// If now is not within the range of available times . . . 

if (!((pq->StartTimeOfDay < UtcNowAsMinutesAfterMidnight) && (utcNowAsMinutesAfterMidnight < pq- 
>UntilTimeOfDay))) 

{ 

available = false; 

} 

} 

return available; 


private static Boolean ReportAvailabilityAtThisTime(PrintQueue pq) 

{ 

Boolean available = true; 

if (pq.StartTimeOfDay != pq.UntilTimeOfDay) // If the printer is not available 24 hours a day 

{ 

DateTime utcNow = DateTime.UtcNow; 

Int32 UtcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + UtcNow.TimeOfDay.Minutes; 

// If now is not within the range of available times . . . 
if (!((pq.StartTimeOfDay < UtcNowAsMinutesAfterMidnight) 

&& 

(UtcNowAsMinutesAfterMidnight < pq.UntilTimeOfDay))) 

{ 

available = false; 

} 

} 

return available; 

}//end ReportAvailabilityAtThisTime 


Private Shared Function ReportAvailabilityAtThisTime(ByVal pq As PrintQueue) As Boolean 
Dim available As Boolean = True 

If pq.StartTimeOfDay <> pq.UntilTimeOfDay Then ' If the printer is not available 24 hours a day 
Dim UtcNow As Date = Date.UtcNow 

Dim UtcNowAsMinutesAfterMidnight As Int32 = (utcNow.TimeOfDay.Hours * 60) + UtcNow.TimeOfDay.Minutes 
' If now is not within the range of available times . . . 

If Not((pq.StartTimeOfDay < UtcNowAsMinutesAfterMidnight) AndAlso (utcNowAsMinutesAfterMidnight < 
pq.UntilTimeOfDay)) Then 

available = False 
End If 
End If 

Return available 

End Eunction 'end ReportAvailabilityAtThisTime 


TheTimeConverter.ConvertToLocaIHumanReadableTime method (presented in the code example below) 
does not use any methods introduced with Microsoft .NET Framework, so the discussion is brief The method has a 
double conversion task: it must take an integer expressing minutes-after-midnight and convert it to a human- 
readable time and it must convert this to the local time. It accomplishes this by first creating a DateTime object that 
is set to midnight UTC and then it uses the AddMinutes method to add the minutes that were passed to the 
method. This returns a new DateTime expressing the original time that was passed to the method. The ToLocalTime 
method then converts this to local time. 



private ref class TimeConverter { 


internal: 

static DateTime ConvertToLocalHumanReadableTime (Int32 timeInMinutesAfterUTCMidnight) 

{ 

// Construct a UTC midnight object. 

// Must start with current date so that the local Daylight Savings system, if any, will be taken into 
account. 

DateTime utcNow = DateTime::UtcMow; 

DateTime utcMidnight = DateTime(utcMow.Year, utcNow.Month, utcNow.Day, 0, 0, 0, DateTimeKind::Utc); 

// Add the minutes passed into the method in order to get the intended UTC time. 

Double minutesAfterUTCMidnight = ((Double)timelnMinutesAfterUTCMidnight); 

DateTime utcTime = utcMidnight.AddMinutes(minutesAfterUTCMidnight)j 

// Convert to local time. 

DateTime localTime = utcTime.ToLocalTime()j 

return localTime; 

}; 

}; 


class TimeConverter 

{ 

// Convert time as minutes past UTC midnight into human readable time in local time zone, 
internal static DateTime ConvertToLocalHumanReadableTime(Int32 timeInMinutesAfterUTCMidnight) 

{ 

// Construct a UTC midnight object. 

// Must start with current date so that the local Daylight Savings system, if any, will be taken into 

account. 

DateTime utcNow = DateTime.UtcNow; 

DateTime utcMidnight = new DateTime(utcNow.Year, utcNow.Month, utcNow.Day, 0, 0, 0, DateTimeKind.Utc) 

// Add the minutes passed into the method in order to get the intended UTC time. 

Double minutesAfterUTCMidnight = (Double)timelnMinutesAfterUTCMidnight; 

DateTime utcTime = utcMidnight.AddMinutes(minutesAfterUTCMidnight); 

// Convert to local time. 

DateTime localTime = utcTime.ToLocalTime(); 

return localTime; 

}// end ConvertToLocalHumanReadableTime 
}//end TimeConverter class 



Friend Class TimeConverter 

' Convert time as minutes past UTC midnight into human readable time in local time zone. 

Friend Shared Function ConvertToLocalHumanReadableTime(ByVal timeInMinutesAfterUTCMidnight As Int32) As 

Date 

' Construct a UTC midnight object. 

' Must start with current date so that the local Daylight Savings system^ if any^ will be taken into 

account. 

Dim utcNow As Date = Date.UtcNow 

Dim utcMidnight As New Date(utcNow.Year, utcNow.Month, utcNow.Day, 0, 0, 0, DateTimeKind.Utc) 

' Add the minutes passed into the method in order to get the intended UTC time. 

Dim minutesAfterUTCMidnight As Double = CType(timeInMinutesAfterUTCMidnight, Double) 

Dim utcTime As Date = utcMidnight.AddMinutes(minutesAfterUTCMidnight) 

' Convert to local time. 

Dim localTime As Date = utcTime.ToLocalTime() 

Return localTime 

End Function ' end ConvertToLocalHumanReadableTime 

End Class 


See also 

• DateTime 

• PrintSystemJobInfo 

• PrintQueue 

• Documents in WPF 

• Printing Overview 



How to: Enumerate a Subset of Print Queues 

2/8/2020 • 2 minutes to read ^ Edit Online 


A common situation faced by information technology (IT) professionals managing a company-wide set of printers 
is to generate a list of printers having certain characteristics. This functionality is provided by the GetPrintQueues 
method of a PrintServer object and the EnumeratedPrintQueueTypes enumeration. 

Example 

In the example below, the code begins by creating an array of flags that specify the characteristics of the print 
queues we want to list. In this example, we are looking for print queues that are installed locally on the print server 
and are shared. The EnumeratedPrintQueueTypes enumeration provides many other possibilities. 

The code then creates a LocalPrintServer object, a class derived from PrintServer. The local print server is the 
computer on which the application is running. 

The last significant step is to pass the array to the GetPrintQueues method. 

Finally, the results are presented to the user. 

// Specify that the list will contain only the print queues that are installed as local and are shared 
array<System: :Printing: :EnumeratedPrintQueueTypes>'' enumerationPlags = 

{EnumeratedPrintQueueTypes::Localj EnumeratedPrintQueueTypes;:Shared}; 

LocalPrintServer'' printServer = gcnew LocalPrintServerQ; 

//Use the enumerationPlags to filter out unwanted print queues 

PrintQueueCollection'' printQueuesOnLocalServer = printServer->GetPrintQueues(enumerationFlags); 

Console::WriteLine("These are your shared, local print queues:\n\n"); 

for each (PrintQueue'' printer in printQueuesOnLocalServer) 

{ 

Console::WriteLine("\tThe shared printer " + printer->Name + " is located at " + printer->Location + "\n"); 

} 

Console::WriteLine("Press enter to continue."); 

Console::ReadLine(); 


// Specify that the list will contain only the print queues that are installed as local and are shared 
EnumeratedPrintQueueTypes[] enumerationPlags = {EnumeratedPrintQueueTypes.Local, 

EnumeratedPrintQueueTypes.Shared}; 

LocalPrintServer printServer = new LocalPrintServerQ; 

//Use the enumerationPlags to filter out unwanted print queues 

PrintQueueCollection printQueuesOnLocalServer = printServer.GetPrintQueues(enumerationFlags); 

Console.WriteLine("These are your shared, local print queues:\n\n"); 

foreach (PrintQueue printer in printQueuesOnLocalServer) 

{ 

Console.WriteLine("\tThe shared printer " + printer.Name + " is located at " + printer.Location + "\n"); 

} 

Console.WriteLineC’Press enter to continue."); 

Console.ReadLineQ; 





' Specify that the list will contain only the print queues that are installed as local and are shared 
Dim enumerationFlagsO As EnumeratedPrintQueueTypes = {EnumeratedPrintQueueTypes.Localj 
EnumeratedPrintQueueTypes.Shared} 

Dim printServer As New LocalPrintServer() 

'Use the enumerationFlags to filter out unwanted print queues 

Dim printQueuesOnLocalServer As PrintQueueCollection = printServer.GetPrintQueues(enumerationFlags) 

Console.WriteLine("These are your shared^ local print queues:" & vbLf & vbLf) 

For Each printer As PrintQueue In printQueuesOnLocalServer 

Console.WriteLine(vbTab & "The shared printer " & printer.Name & " is located at " & printer.Location & 
VbLf) 

Next printer 

Console.WriteLineC’Press enter to continue.") 

Console.ReadLineO 

You could extend this exannple by having the foreach loop that steps through each print queue do further 
screening. For example, you could screen out printers that do not support two-sided printing by having the loop 
call each print queue's GetPrintCapabilities method and test the returned value for the presence of duplexing. 

See also 

• GetPrintQueues 

• PrintServer 

• LocalPrintServer 

• EnumeratedPrintQueueTypes 

• PrintQueue 

• GetPrintCapabilities 

• Documents in WPF 

• Printing Qverview 

• Microsoft XPS Document Writer 




How to: Get Print System Object Properties Without 
Reflection 

4/9/2019 • 2 minutes to read i Edit Online 


Using reflection to itemize the properties (and the types of those properties) on an object can slow application 
performance. The System.Printing.IndexedProperties namespace provides a means to getting this information with 
using reflection. 

Example 

The steps for doing this are as follows. 

1. Create an instance of the type. In the example below, the type is the PrintQueue type that ships with 
Microsoft .NET Framework, but nearly identical code should work for types that you derive from 
PrintSystemObject. 

2. Create a PrintPropertyDictionary from the type's PropertiesCollection. The Value property of each entry in 
this dictionary is an object of one of the types derived from PrintProperty. 

3. Enumerate the members of the dictionary. For each of them, do the following. 

4. Up-cast the value of each entry to PrintProperty and use it to create a PrintProperty object. 

5. Get the type of the Value of each of the PrintProperty object. 


// Enumerate the propertieSj and their typeSj of a queue without using Reflection 

LocalPrintServer localPrintServer = new LocalPrintServer()j 

PrintQueue defaultPrintQueue = LocalPrintServer.GetDefaultPrintQueue(); 

PrintPropertyDictionary printQueueProperties = defaultPrintQueue.PropertiesCollection; 

Console.WriteLine("These are the properties, and their types, of {0}, a {!}", defaultPrintQueue.Name, 
defaultPrintQueue.GetTypeO .ToStringO +"\n"); 

foreach (DictionaryEntry entry in printQueueProperties) 

{ 

PrintProperty property = (PrintProperty)entry.Value; 

if (property.Value != null) 

{ 

Console.WriteLine(property.Name + "\t(Type: {0})", property.Value.GetType() .ToStringO); 

} 

} 

Console.WriteLine("\n\nPress Return to continue..."); 

Console.ReadLineO; 





' Enumerate the properties^ and their types, of a queue without using Reflection 
Dim localPrintServer As New LocalPrintServer() 

Dim defaultPrintQueue As PrintQueue = LocalPrintServer.GetDefaultPrintQueue() 

Dim printQueueProperties As PrintPropertyDictionary = defaultPrintQueue.PropertiesCollection 

Console.WriteLine("These are the properties, and their types, of {0}, a {1}", defaultPrintQueue.Name, 
defaultPrintQueue.GetTypeO .ToStringO + vbLf) 

For Each entry As DictionaryEntry In printQueueProperties 

Dim [property] As PrintProperty = CType(entry.Value, PrintProperty) 

If [property].Value IsNot Nothing Then 

Console.WriteLine([property].Name & vbTab & "(Type: {0})", [property].Value.GetType().ToStringO) 
End If 
Next entry 

Console.WriteLine(vbLf & vbLf & "Press Return to continue...") 

Console.ReadLineO 


See also 

• PrintProperty 

• PrintSystemObject 

• System.Printing.IndexedProperties 

• PrintPropertyDictionary 

• LocalPrintServer 

• PrintQueue 

• DictionaryEntry 

• Documents in WPF 

• Printing Overview 



How to: Programmatically Print XPS Files 

11/12/2019 • 7 minutes to read ^ Edit Online 


You can use one overload of the AddJob method to print XML Paper Specification (XPS) files without opening a 
PrintDialog or, in principle, any user interface (Ul) at all. 

You can also print XPS files using the many XpsDocumentWriter.Write and XpsDocumentWriter.WriteAsync 
methods. For more information, see Printing an XPS Document. 

Another way of printing XPS is to use the PrintDialog.PrintDocument or PrintDialog.PrintVisual methods. See 
Invoke a Print Dialog. 

Example 

The main steps to using the three-parameter AddJob(String, String, Boolean) method are as follows. The example 
below gives details. 

1. Determine if the printer is an XPSDrv printer. See Printing Overview for more about XPSDrv. 

2. If the printer is not an XPSDrv printer, set the thread's apartment to single thread. 

3. Instantiate a print server and print queue object. 

4. Call the method, specifying a job name, the file to be printed, and a Boolean flag indicating whether or not 
the printer is an XPSDrv printer. 

The example below shows how to batch print all XPS files in a directory. Although the application prompts the user 
to specify the directory, the three-parameter AddJob(String, String, Boolean) method does not require a user 
interface (Ul). It can be used in any code path where you have an XPS file name and path that you can pass to it. 

The three-parameter AddJob(String, String, Boolean) overload of AddJob must run in a single thread apartment 
whenever the Boolean parameter is false , which it must be when a non-XPSDrv printer is being used. However, 
the default apartment state for .NET is multiple thread. This default must be reversed since the example assumes a 
non-XPSDrv printer. 

There are two ways to change the default. One way is to simply add the STAThreadAttribute (that is," 

[System.STAThneadAttributeO] ") just above the first line of the application's Main method (usually " 
static void Main(string[ ] args) "). However, many applications require that the Main method have a multi¬ 
threaded apartment state, so there is a second method: put the call to AddJob(String, String, Boolean) in a separate 
thread whose apartment state is set to STA with SetApartmentState. The example below uses this second 
technique. 

Accordingly, the example begins by instantiating a Thread object and passing it a PrintXPS method as the 
ThreadStart parameter. (The PrintXPS method is defined later in the example.) Next the thread is set to a single 
thread apartment. The only remaining code of the Main method starts the new thread. 

The meat of the example is in the static BatchXPSPrinter.PrintXPS method. After creating a print server and 
queue, the method prompts the user for a directory containing XPS files. After validating the existence of the 
directory and the presence of *.xps files in it, the method adds each such file to the print queue. The example 
assumes that the printer is non-XPSDrv, so we are passing false to the last parameter of AddJob(String, String, 
Boolean) method. For this reason, the method will validate the XPS markup in the file before it attempts to convert 
it to the printer's page description language. If the validation fails, an exception is thrown. The example code will 
catch the exception, notify the user about it, and then go on to process the next XPS file. 









class Program 

{ 

[System.MTAThreadAttributeO] // Added for clarityj but this line is redundant because MTA is the default, 
static void Main(string[] args) 

{ 

// Create the secondary thread and pass the printing method for 

// the constructor's ThreadStart delegate parameter. The BatchXPSPrinter 

// class is defined below. 

Thread printingThread = new Thread(BatchXPSPrinter.PrintXPS)j 

// Set the thread that will use PrintQueue.Addlob to single threading. 
printingThread.SetApartmentState(ApartmentState.STA)j 

// Start the printing thread. The method passed to the Thread 

// constructor will execute. 

printingThread.StartO; 

}//end Main 
}//end Program class 

public class BatchXPSPrinter 

{ 

public static void PrintXPS() 

{ 

// Create print server and print queue. 

LocalPrintServer localPrintServer = new LocalPrintServer()j 
PrintQueue defaultPrintQueue = LocalPrintServer.GetDefaultPrintQueue(); 

// Prompt user to identify the directoryj and then create the directory object. 

Console.Write("Enter the directory containing the XPS files: "); 

String directoryPath = Console.ReadLine(); 

Directoryinfo dir = new Directorylnfo(directoryPath)j 

// If the user mistyped^ end the thread and return to the Main thread, 
if (!dir.Exists) 

{ 

Console.WriteLine("There is no such directory."); 

} 

else 

{ 

// If there are no XPS files in the directory, end the thread 
// and return to the Main thread, 
if (dir.GetFiles("*.xps").Length == 0) 

{ 

Console.WriteLine("There are no XPS files in the directory."); 

} 

else 

{ 

Console.WriteLine("\nIobs will now be added to the print queue."); 

Console.WriteLine("If the queue is not paused and the printer is working, jobs will begin 

printing."); 

// Batch process all XPS files in the directory, 
foreach (Fileinfo f in dir.GetFiles("*.xps")) 

{ 

String nextFile = directoryPath + "\\" + f.Name; 

Console.WriteLine("Adding {0} to queue.", nextFile); 

try 

{ 

// Print the Xps file while providing XPS validation and progress notifications. 
PrintSystemlobInfo xpsPrintlob = defaultPrintQueue.Add]ob(f.Name, nextFile, false); 

} 

catch (PrintlobException e) 

{ 

Console.WriteLine("\n\t{0} could not be added to the print queue.", f.Name); 
if (e.InnerException.Message == "File contains corrupted data.") 

{ 

Console.WriteLine("\tIt is not a valid XPS file. Use the isXPS Conformance Tool to 


debug it."); 


} 

Console.WniteLineCXtContinuing with next XPS file.\n"); 


} 

}// end for each XPS file 
}//end if there are no XPS files in the directory 
}//end if the directory does not exist 

Console.WriteLine("Press Enter to end program."); 
Console. Read Line 0; 

}// end PrintXPS method 
}// end BatchXPSPrinter class 


Friend Class Program 

<System.MTAThreadAttribute()> 

Shared Sub Main(By\/al args() As String) ' Added for clarity, but this line is redundant because MTA is the 
default. 

' Create the secondary thread and pass the printing method for 
' the constructor's ThreadStart delegate parameter. The BatchXPSPrinter 
' class is defined below. 

Dim printingThread As New Thread(AddressOf BatchXPSPrinter.PrintXPS) 

' Set the thread that will use PrintQueue.Addlob to single threading. 
printingThread.SetApartmentState(ApartmentState.STA) 

' Start the printing thread. The method passed to the Thread 

' constructor will execute. 

printingThread.StartO 

End Sub 

End Class 

Public Class BatchXPSPrinter 

Public Shared Sub PrintXPS() 

' Create print server and print queue. 

Dim localPrintServer As New LocalPrintServer() 

Dim defaultPrintQueue As PrintQueue = LocalPrintServer.GetDefaultPrintQueue() 

' Prompt user to identify the directory, and then create the directory object. 

Console.Write("Enter the directory containing the XPS files: ") 

Dim directoryPath As String = Console.ReadLine() 

Dim dir As New Directorylnfo(directoryPath) 

' If the user mistyped, end the thread and return to the Main thread. 

If Not dir.Exists Then 

Console.WriteLine("There is no such directory.") 

Else 

' If there are no XPS files in the directory, end the thread 
' and return to the Main thread. 

If dir.GetFilesC*.xps"). Length = 0 Then 

Console.WriteLine("There are no XPS files in the directory.") 

Else 

Console.WriteLine(vbLf & "lobs will now be added to the print queue.") 

Console.WriteLine("If the queue is not paused and the printer is working, jobs will begin 

printing.") 

' Batch process all XPS files in the directory. 

For Each f As Fileinfo In dir.GetFiles("*.xps") 

Dim nextFile As String = directoryPath & "\" & f.Name 
Console.WriteLine("Adding {0} to queue.", nextFile) 

Try 

' Print the Xps file while providing XPS validation and progress notifications. 

Dim xpsPrintlob As PrintSystemlobInfo = defaultPrintQueue.AddIob(f.Name, nextFile, 

False) 

Catch e As PrintlobException 


Console.Wr'iteLine(vbLf & vbTab & "{0} could not be added to the print queue.", f.Name) 
If e.InnerException.Message = "File contains corrupted data." Then 

Console.WriteLine(vbTab & "It is not a valid XPS file. Use the isXPS Conformance 

Tool to debug it.") 

End If 

Console.WriteLine(vbTab & "Continuing with next XPS file." & vbLf) 

End Try 

Next f ' end for each XPS file 

End If 'end if there are no XPS files in the directory 

End If 'end if the directory does not exist 

Console.WriteLine("Press Enter to end program.") 

Console.ReadLine() 

End Sub 

End Class 

If you are using an XPSDrv printer, then you can set the final parameter to true . In that case, since XPS is the 
printer's page description language, the method will send the file to the printer without validating it or converting 
it to another page description language. If you are uncertain at design time whether the application will be using 
an XPSDrv printer, you can modify the application to have it read the IsXpsDevice property and branch according 
to what it finds. 

Since there will initially be few XPSDrv printers available immediately after the release of Windows Vista and 
Microsoft .NET Framework, you may need to disguise a non-XPSDrv printer as an XPSDrv printer. To do so, add 
Pipelineconfig.xml to the list of files in the following registry key of the computer running your application: 

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\Environments\Windows NT 
x86\Drivers\Version-3\<A5eiyryoA'A5AT/r7teT>\DependentFiles 

where <PseucloXPSPrinter> is any print queue. The machine must then be rebooted. 

This disguise will enable you to pass true as the final parameter of AddJobfString, String, Boolean) without 
causing an exception, but since <PseudoXPSPrinter> is not really an XPSDrv printer, only garbage will print. 


NOTE 

For simplicity, the example above uses the presence of an *.xps extension as its test that a file is XPS. Flowever, XPS files do 
not have to have this extension. The isXPS.exe (isXPS Conformance Tool) is one way of testing a file for XPS validity. 


See also 

• PrintQueue 

• AddJob 

• ApartmentState 

• STAThreadAttribute 

• XPS Documents 

• Printing an XPS Document 

• Managed and Unmanaged Threading 

• isXPS.exe (isXPS Conformance Tool) 

• Documents in WPF 

• Printing Overview 





How to: Remotely Survey the Status of Printers 

3/12/2020 • 13 minutes to read ^ Edit Online 


At any given time at medium and large companies there may be multiple printers that are not working due to a 
paper jam or being out of paper or some other problematic situation. The rich set of printer properties exposed in 
the APIs of Microsoft .NET Framework provide a means for performing a rapid survey of the states of printers. 

Example 

The major steps for creating this kind of utility are as follows. 

1. Obtain a list of all print servers. 

2. Loop through the servers to query their print queues. 

3. Within each pass of the server loop, loop through all the server's queues and read each property that might 
indicate that the queue is not currently working. 

The code below is a series of snippets. For simplicity, this example assumes that there is a CRLF-delimited list of 
print servers. The variable fiieOfPrintservens is a StreamReader object for this file. Since each server name is on 
its own line, any call of ReadLine gets the name of the next server and moves the Stream Reader's cursor to the 
beginning of the next line. 

Within the outer loop, the code creates a PrintServer object for the latest print server and specifies that the 
application is to have administrative rights to the server. 


NOTE 

If there are a lot of servers, you can improve performance by using the PrintServer(String, String!], PrintSystemDesiredAccess) 
constructors that only initialize the properties you are going to need. 


The example then uses GetPrintQueues to create a collection of all of the server's queues and begins to loop 
through them. This inner loop contains a branching structure corresponding to the two ways of checking a printer's 
status: 

• You can read the flags of the QueueStatus property which is of type PrintQueueStatus. 

• You can read each relevant property such as IsOutOfPaper, and IsPaperJammed. 

This example demonstrates both methods, so the user was previously prompted as to which method to use and 
responded with "y" if they wanted to use the flags of the QueueStatus property. See below for the details of the two 
methods. 


Finally, the results are presented to the user. 






// Survey queue status for every queue on every print server 
System: :String'' line; 

System::String* statusReport = "\n\nAny problem states are indicated below:\n\n"; 
while ((line = fileOfPrintServers->ReadLine()) != nullptr) 

{ 

System: :Printing: :PrintServer'' myPS = gcnew System: :Printing: :PrintServer(line, 
PrintSystemDesiredAccess::AdmlnistrateServer); 

System: :Printing: :PrintQueueCollection'' myPrintQueues = myPS->GetPrintQueues(); 

statusReport = statusReport + "\n" + line; 

for each (System::Printing::PrintQueue* pq in myPrintQueues) 

{ 

pq->Refresh(); 

statusReport = statusReport + "\n\t" + pq->Name + 
if (useAttributesResponse == "y") 

{ 

TroubleSpotter::SpotTroubleUsingQueueAttributes(statusReport, pq); 

// TroubleSpotter class is defined in the complete example. 

} else 

{ 

TroubleSpotter::SpotTroubleUsingProperties(statusReportj pq); 

} 

} 

} 

fileOfPrintServers->Close(); 

Console::WriteLine(statusReport); 

Console::WriteLine("\nPress Return to continue."); 

Console::ReadLine(); 


// Survey queue status for every queue on every print server 
String line; 

String statusReport = "\n\nAny problem states are indicated below:\n\n"; 
while ((line = fileOfPrintServers.ReadLine()) != null) 

{ 

PrintServer myPS = new PrintServer(linej PrintSystemDesiredAccess.AdmlnistrateServer) 
PrintQueueCollection myPrintQueues = myPS.GetPrintQueues(); 
statusReport = statusReport + "\n" + line; 
foreach (PrintQueue pq in myPrintQueues) 

{ 

pq.Refresh(); 

statusReport = statusReport + "\n\t" + pq.Name + 
if (useAttributesResponse == "y") 

{ 

TroubleSpotter.SpotTroubleUsingQueueAttributes(ref statusReportj pq); 

// TroubleSpotter class is defined in the complete example. 

} 

else 

{ 

TroubleSpotter.SpotTroubleUsingProperties(ref statusReport, pq); 

} 

}// end for each print queue 

}// end while list of print servers is not yet exhausted 

fileOfPrintServers.Close(); 

Console.WriteLine(statusReport); 

Console.WriteLine("\nPress Return to continue."); 

Console. ReadLineO; 



' Survey queue status for every queue on every print server 
Dim line As String 

Dim statusReport As String = vbLf & vbLf & "Any problem states are indicated below:" & vbLf & vbLf 
line = fileOfPrintServers. ReadLineO 
Do While line IsNot Nothing 

Dim myPS As New PrintServer(linej PrintSystemDesiredAccess.AdministrateServer) 

Dim myPrintQueues As PrintQueueCollection = myPS.GetPrintQueues() 
statusReport = statusReport & vbLf & line 
For Each pq As PrintQueue In myPrintQueues 
pq.Refresh() 

statusReport = statusReport & vbLf & vbTab & pq.Name & 

If useAttributesResponse = "y" Then 

TroubleSpotter.SpotTroubleLlsingQueueAttributes(statusReportj pq) 

' TroubleSpotter class is defined in the complete example. 

Else 

TroubleSpotter.SpotTroubleLlslngProperties(statusReportj pq) 

End If 

Next pq ' end for each print queue 

line = fileOfPrintServers. ReadLineO 
Loop ' end while list of print servers is not yet exhausted 

fileOfPrintServers.Close() 

Console.WriteLine(statusReport) 

Console.WriteLine(vbLf & "Press Return to continue.") 

Console. ReadLineO 


To check printer status using the flags of the QueueStatus property, you check each relevant flag to see if it is set. 
The standard way to see if one bit is set in a set of bit flags is to perform a logical AND operation with the set of 
flags as one operand and the flag itself as the other. Since the flag itself has only one bit set, the result of the logical 
AND is that, at most, that same bit is set. To find out whether it is or not, just compare the result of the logical AND 
with the flag itself For more information, see PrintQueueStatus, the & Operator (C# Reference), and FlagsAttribute. 

For each attribute whose bit is set, the code adds a notice to the final report that will be presented to the user. (The 
ReportAvailabilityAtThisTime method that is called at the end of the code is discussed below.) 



internal: 

// Check for possible trouble states of a printer using the flags of the QueueStatus property 

static void SpotTroubleUsingQueueAttributes (System::String''% statusKeport, System:rPrinting::PrintQueue^ 

pq) 

{ 

if ((pq->QueueStatus & PrintQueueStatus::PaperProblem) == PrintQueueStatus::PaperProblem) 

{ 

statusReport = statusReport + "Has a paper problem, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::NoToner) == PrintQueueStatus::NoToner) 

{ 

statusReport = statusReport + "Is out of toner, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::DoorOpen) == PrintQueueStatus::DoorOpen) 

{ 

statusReport = statusReport + "Has an open door. 

} 

if ((pq->QueueStatus & PrintQueueStatus::Error) == PrintQueueStatus::Error) 

{ 

statusReport = statusReport + "Is in an error state. 

} 

if ((pq->QueueStatus & PrintQueueStatus::NotAvailable) == PrintQueueStatus::NotAvailable) 

{ 

statusReport = statusReport + "Is not available. 

} 

if ((pq->QueueStatus & PrintQueueStatus::Offline) == PrintQueueStatus::Offline) 

{ 

statusReport = statusReport + "Is off line, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::OutOfMemory) == PrintQueueStatus::OutOfMemory) 

{ 

statusReport = statusReport + "Is out of memory. 

} 

if ((pq->QueueStatus & PrintQueueStatus::PaperOut) == PrintQueueStatus::PaperOut) 

{ 

statusReport = statusReport + "Is out of paper, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::OutputBinFull) == PrintQueueStatus::OutputBinFull) 

{ 

statusReport = statusReport + "Has a full output bin. "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::Paper]am) == PrintQueueStatus::Paperlam) 

{ 

statusReport = statusReport + "Has a paper jam. "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::Paused) == PrintQueueStatus::Paused) 

{ 

statusReport = statusReport + "Is paused, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::TonerLow) == PrintQueueStatus::TonerLow) 

{ 

statusReport = statusReport + "Is low on toner, "j 

} 

if ((pq->QueueStatus & PrintQueueStatus::LlserIntervention) == PrintQueueStatus::UserIntervention) 

{ 

statusReport = statusReport + "Needs user intervention, "j 

} 

// Check if queue is even available at this time of day 
// The method below is defined in the complete example. 

ReportAvailabilityAtThisTime(statusReport, pq)j 



// Check for possible trouble states of a printer using the flags of the QueueStatus property 
internal static void SpotTroubleUsingQueueAttributes(ref String statusReportj PrintQueue pq) 

{ 

if ((pq.QueueStatus & PrintQueueStatus.PaperProblem) == PrintQueueStatus.PaperProblem) 

{ 

statusReport = statusReport + "Has a paper problem. 

} 

if ((pq.QueueStatus & PrintQueueStatus.NoToner) == PrintQueueStatus.NoToner) 

{ 

statusReport = statusReport + "Is out of toner. 

} 

if ((pq.QueueStatus & PrintQueueStatus.DoorOpen) == PrintQueueStatus.DoorOpen) 

{ 

statusReport = statusReport + "Has an open door, "j 

} 

if ((pq.QueueStatus & PrintQueueStatus.Error) == PrintQueueStatus.Error) 

{ 

statusReport = statusReport + "Is in an error state, "j 

} 

if ((pq.QueueStatus & PrintQueueStatus.NotAvailable) == PrintQueueStatus.NotAvailable) 

{ 

statusReport = statusReport + "Is not available, "j 

} 

if ((pq.QueueStatus & PrintQueueStatus.Offline) == PrintQueueStatus.Offline) 

{ 

statusReport = statusReport + "Is off line. 

} 

if ((pq.QueueStatus & PrintQueueStatus.OutOfMemory) == PrintQueueStatus.OutOfMemory) 

{ 

statusReport = statusReport + "Is out of memory, "j 

} 

if ((pq.QueueStatus & PrintQueueStatus.PaperOut) == PrintQueueStatus.PaperOut) 

{ 

statusReport = statusReport + "Is out of paper. 

} 

if ((pq.QueueStatus & PrintQueueStatus.OutputBinFull) == PrintQueueStatus.OutputBinFull) 

{ 

statusReport = statusReport + "Has a full output bin. 

} 

if ((pq.QueueStatus & PrintQueueStatus.Paperlam) == PrintQueueStatus.Paperlam) 

{ 

statusReport = statusReport + "Has a paper jam. 

} 

if ((pq.QueueStatus & PrintQueueStatus.Paused) == PrintQueueStatus.Paused) 

{ 

statusReport = statusReport + "Is paused. 

} 

if ((pq.QueueStatus & PrintQueueStatus.TonerLow) == PrintQueueStatus.TonerLow) 

{ 

statusReport = statusReport + "Is low on toner. 

} 

if ((pq.QueueStatus & PrintQueueStatus.Userlntervention) == PrintQueueStatus.Userlntervention) 

{ 

statusReport = statusReport + "Heeds user intervention. 

} 

// Check if queue is even available at this time of day 
// The method below is defined in the complete example. 

ReportAvailabilityAtThisTime(ref statusReport, pq)j 



' Check for possible trouble states of a printer using the flags of the QueueStatus property 
Friend Shared Sub SpotTroubleUsingQueueAttributes(ByRef statusReport As Strings ByVal pq As PrintQueue) 
If (pq.QueueStatus And PrintQueueStatus.PaperProblem) = PrintQueueStatus.PaperProblem Then 
statusReport = statusReport & "Has a paper problem. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.NoToner) = PrintQueueStatus.NoToner Then 
statusReport = statusReport & "Is out of toner. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.DoorOpen) = PrintQueueStatus.DoorOpen Then 
statusReport = statusReport & "Has an open door. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.Error) = PrintQueueStatus.Error Then 
statusReport = statusReport & "Is in an error state. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.NotAvailable) = PrintQueueStatus.NotAvailable Then 
statusReport = statusReport & "Is not available. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.Offline) = PrintQueueStatus.Offline Then 
statusReport = statusReport & "Is off line. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.OutOfMemory) = PrintQueueStatus.OutOfMemory Then 
statusReport = statusReport & "Is out of memory. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.PaperOut) = PrintQueueStatus.PaperOut Then 
statusReport = statusReport & "Is out of paper. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.OutputBinEull) = PrintQueueStatus.OutputBinPull Then 
statusReport = statusReport & "Has a full output bin. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.Paperlam) = PrintQueueStatus.Paperlam Then 
statusReport = statusReport & "Has a paper jam. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.Paused) = PrintQueueStatus.Paused Then 
statusReport = statusReport & "Is paused. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.TonerLow) = PrintQueueStatus.TonerLow Then 
statusReport = statusReport & "Is low on toner. " 

End If 

If (pq.QueueStatus And PrintQueueStatus.Userintervention) = PrintQueueStatus.Userlntervention Then 
statusReport = statusReport & "Heeds user intervention. " 

End If 


' Check if queue is even available at this time of day 
' The method below is defined in the complete example. 
ReportAvallabilityAtThisTlme(statusReportj pq) 

End Sub 


To check printer status using each property, you simply read each property and add a note to the final report that 
will be presented to the user if the property is true . (The ReportAvailabilityAtThisTime method that is called at 
the end of the code is discussed below.) 




internal: 

// Check for possible trouble states of a printer using its properties 

static void SpotTroubleUsingProperties (System: :String''% statusReportj System: :Printing: :PrintQueue'' pq) 

{ 

if (pq->HasPaperProblem) 

{ 

statusReport = statusReport + "Has a paper problem, "j 

} 

if (!(pq->HasToner)) 

{ 

statusReport = statusReport + "Is out of toner, "j 

} 

if (pq->IsDoorOpened) 

{ 

statusReport = statusReport + "Has an open door. 

} 

if (pq->IsInError) 

{ 

statusReport = statusReport + "Is in an error state. 

} 

if (pq->IsNotAvailable) 

{ 

statusReport = statusReport + "Is not available. 

} 

if (pq->IsOffline) 

{ 

statusReport = statusReport + "Is off line, "j 

} 

if (pq->IsOutOfMemory) 

{ 

statusReport = statusReport + "Is out of memory. 

} 

if (pq->IsOutOfPaper) 

{ 

statusReport = statusReport + "Is out of paper, "j 

} 

if (pq->IsOutputBinFull) 

{ 

statusReport = statusReport + "Has a full output bin. "j 

} 

if (pq->IsPaper3ammed) 

{ 

statusReport = statusReport + "Has a paper jam. "j 

} 

if (pq->IsPaused) 

{ 

statusReport = statusReport + "Is paused. 

} 

if (pq->IsTonerLow) 

{ 

statusReport = statusReport + "Is low on toner, "j 

} 

if (pq->NeedLlserIntervention) 

{ 

statusReport = statusReport + "Needs user intervention, "j 

} 

// Check if queue is even available at this time of day 
// The following method is defined in the complete example. 

ReportAvailabilityAtThisTime(statusReport, pq)j 



// Check for possible trouble states of a printer using its properties 

internal static void SpotTroubleUsingProperties(ref String statusReport, PrintQueue pq) 

{ 

if (pq.HasPaperProblem) 

{ 

statusReport = statusReport + "Has a paper problem. 

} 

if (!(pq.HasToner)) 

{ 

statusReport = statusReport + "Is out of toner. 

} 

if (pq.IsDoorOpened) 

{ 

statusReport = statusReport + "Has an open door, "j 

} 

if (pq.IsInError) 

{ 

statusReport = statusReport + "Is in an error state, "j 

} 

if (pq.IsNotAvailable) 

{ 

statusReport = statusReport + "Is not available, "j 

} 

if (pq.IsOffline) 

{ 

statusReport = statusReport + "Is off line. 

} 

if (pq.IsOutOfMemory) 

{ 

statusReport = statusReport + "Is out of memory, "j 

} 

if (pq.IsOutOfPaper) 

{ 

statusReport = statusReport + "Is out of paper. 

} 

if (pq.IsOutputBinFull) 

{ 

statusReport = statusReport + "Has a full output bin. 

} 

if (pq.IsPaperlammed) 

{ 

statusReport = statusReport + "Has a paper jam. 

} 

if (pq.IsPaused) 

{ 

statusReport = statusReport + "Is paused. 

} 

if (pq.IsTonerLow) 

{ 

statusReport = statusReport + "Is low on toner, "j 

} 

if (pq.NeedUserIntervention) 

{ 

statusReport = statusReport + "Heeds user intervention. 

} 

// Check if queue is even available at this time of day 
// The following method is defined in the complete example. 
ReportAvailabilityAtThisTime(ref statusReport, pq)j 
}//end SpotTroubleUsingProperties 



' Check for possible trouble states of a printer using its properties 

Friend Shared Sub SpotTroubleUsingProperties(ByRef statusReport As String, ByVal pq As PrintQueue) 
If pq.HasPaperProblem Then 

statusReport = statusReport & "Has a paper problem. " 

End If 

If Not(pq.HasToner) Then 

statusReport = statusReport & "Is out of toner. " 

End If 

If pq.IsDoorOpened Then 

statusReport = statusReport & "Has an open door. " 

End If 

If pq.IsInError Then 

statusReport = statusReport & "Is in an error state. " 

End If 

If pq.IsNotAvailable Then 

statusReport = statusReport & "Is not available. " 

End If 

If pq.IsOffline Then 

statusReport = statusReport & "Is off line. " 

End If 

If pq.IsOutOfMemory Then 

statusReport = statusReport & "Is out of memory. " 

End If 

If pq.IsOutOfPaper Then 

statusReport = statusReport & "Is out of paper. " 

End If 

If pq.IsOutputBinFull Then 

statusReport = statusReport & "Has a full output bin. " 

End If 

If pq.IsPaperlammed Then 

statusReport = statusReport & "Has a paper jam. " 

End If 

If pq.IsPaused Then 

statusReport = statusReport & "Is paused. " 

End If 

If pq.IsTonerLow Then 

statusReport = statusReport & "Is low on toner. " 

End If 

If pq.NeedUserIntervention Then 

statusReport = statusReport & "Meeds user intervention. " 

End If 

' Check if queue is even available at this time of day 
' The following method is defined in the complete example. 

ReportAvallabilityAtThisTlme(statusReport, pq) 

End Sub 


The ReportAvailabilityAtThisTime method was created in case you need to determine if the queue is available 
at the current time of day. 

The method will do nothing if the StartTimeOfDay and UntilTimeOfDay properties are equal; because in that case 
the printer is available at all times. If they are different, the method gets the current time which then has to be 
converted into total minutes past midnight because the StartTimeOfDay and UntilTimeOfDay properties are Int32s 
representing minutes-after-midnight, not DateTime objects. Finally, the method checks to see if the current time is 
between the start and "until" times. 



private: 

static void ReportAvailabilityAtThisTime (System: :String''% statusReportj System: :Printing: :PrintQueue'' pq) 

{ 

if (pq->StartTimeOfDay != pq->LlntilTimeOfDay) 

{ 

System: :DateTime utcNow = DateTime: :LltcNow; 

System::Int32 utcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + 

UtcNow.TimeOfDay.Minutes; 

// If now is not within the range of available times . . . 

if (!((pq->StartTimeOfDay < UtcNowAsMinutesAfterMidnight) && (utcNowAsMinutesAfterMidnight < pq- 
>UntilTimeOfDay))) 

{ 

statusReport = statusReport + " Is not available at this time of day. 

} 

} 

}; 


private static void ReportAvailabilityAtThisTime(ref String statusReportj PrintQueue pq) 

{ 

if (pq.StartTimeOfDay != pq.UntilTimeOfDay) // If the printer is not available 24 hours a day 

{ 

DateTime utcNow = DateTime.UtcNow; 

Int32 UtcNowAsMinutesAfterMidnight = (utcNow.TimeOfDay.Hours * 60) + UtcNow.TimeOfDay.Minutes; 

// If now is not within the range of available times . . . 
if (!((pq.StartTimeOfDay < UtcNowAsMinutesAfterMidnight) 

&& 

(UtcNowAsMinutesAfterMidnight < pq.UntilTimeOfDay))) 

{ 

statusReport = statusReport + " Is not available at this time of day. "; 

} 

} 

} 


Private Shared Sub ReportAvailabilityAtThisTime(ByRef statusReport As Strings ByVal pq As PrintQueue) 

If pq.StartTimeOfDay <> pq.UntilTimeOfDay Then ' If the printer is not available 24 hours a day 
Dim UtcNow As Date = Date.UtcNow 

Dim UtcNowAsMinutesAfterMidnight As Int32 = (utcNow.TimeOfDay.Hours * 60) + UtcNow.TimeOfDay.Minutes 
' If now is not within the range of available times . . . 

If Not((pq.StartTlmeOfDay < UtcNowAsMinutesAfterMidnight) AndAlso (utcNowAsMinutesAfterMidnight < 
pq.UntilTimeOfDay)) Then 

statusReport = statusReport & " Is not available at this time of day. " 

End If 
End If 
End Sub 


See also 

• StartTimeOfDay 

• UntilTimeOfDay 

• DateTime 

• PrintQueueStatus 

• FlagsAttribute 

• GetPrintQueues 

• PrintServer 

• LocalPrintServer 



EnumeratedPrintQueueTypes 

PrintQueue 

& Operator (C# Reference) 
Documents in WPF 
Printing Overview 


How to: Validate and Merge PrintTickets 

2/8/2020 • 8 minutes to read ^ Edit Online 


The Microsoft Windows Print Schema includes the flexible and extensible PrintCapabilities and PrintTicket 
elements. The former itemizes the capabilities of a print device and the latter specifies how the device should use 
those capabilities with respect to a particular sequence of documents, individual document, or individual page. 

A typical sequence of tasks for an application that supports printing would be as follows. 

1. Determine a printer's capabilities. 

2. Configure a PrintTicket to use those capabilities. 

3. Validate the PrintTicket. 

This article shows how to do this. 

Example 

In the simple example below, we are interested only in whether a printer can support duplexing — two-sided 
printing. The major steps are as follows. 

1. Get a PrintCapabilities object with the GetPrintCapabilities method. 

2. Test for the presence of the capability you want. In the example below, we test the DuplexingCapability 
property of the PrintCapabilities object for the presence of the capability of printing on both sides of a sheet 
of paper with the "page turning" along the long side of the sheet. Since DuplexingCapability is a collection, 
we use the contains method of ReadOnlyCollection<T>. 


NOTE 

This step is not strictly necessary. The MergeAndValidatePrintTicket method used below will check each request in the 
PrintTicket against the capabilities of the printer. If the requested capability is not supported by printer, the printer 
driver will substitute an alternative request in the PrintTicket returned by the method. 


3. If the printer supports duplexing, the sample code creates a PrintTicket that asks for duplexing. But the 
application does not specify every possible printer setting available in the PrintTicket element. That would be 
wasteful of both programmer and program time. Instead, the code sets only the duplexing request and then 
merges this PrintTicket with an existing, fully configured and validated, PrintTicket, in this case, the user's 
default PrintTicket. 

4. Accordingly, the sample calls the MergeAndValidatePrintTicket method to merge the new, minimal, 
PrintTicket with the user's default PrintTicket. This returns a ValidationResult that includes the new 
PrintTicket as one of its properties. 

5. The sample then tests that the new PrintTicket requests duplexing. If it does, then the sample makes it the 
new default print ticket for the user. If step 2 above had been left out and the printer did not support 
duplexing along the long side, then the test would have resulted in false . (See the note above.) 

6. The last significant step is to commit the change to the UserPrintTicket property of the PrintQueue with the 
Commit method. 







Ill <summary> 

III Changes the user-default PrintTicket setting of the specified print queue. 

Ill </summary> 

III <param name="queue">the printer whose user-default PrintTicket setting needs to be changed</param> 
static private void ChangePrintTicketSetting(PrintQueue queue) 

{ 

// 

// Obtain the printer's PrintCapabilities so we can determine whether or not 
// duplexing printing is supported by the printer. 

// 

PrintCapabilities printcap = queue.GetPrintCapabilities(); 

// 

// The printer's duplexing capability is returned as a read-only collection of duplexing options 
// that can be supported by the printer. If the collection returned contains the duplexing 
// option we want to set^ it means the duplexing option we want to set is supported by the printer^ 

// so we can make the user-default PrintTicket setting change. 

// 

if (printcap.DuplexingCapability.Contains(Duplexing.TwoSidedLongEdge)) 

{ 

// 

// To change the user-default PrintTicket, we can first create a delta PrintTicket with 
// the new duplexing setting. 

// 

PrintTicket deltaTicket = new PrintTicket(); 
deltaTicket.Duplexing = Duplexing.TwoSidedLongEdgej 

// 

// Then merge the delta PrintTicket onto the printer's current user-default PrintTicket, 

// and validate the merged PrintTicket to get the new PrintTicket we want to set as the 
// printer's new user-default PrintTicket. 

// 

ValidationResult result = queue.MergeAndValidatePrintTicket(queue.UserPrintTicket, deltaTicket); 

// 

// The duplexing option we want to set could be constrained by other PrintTicket settings 
// or device settings. We can check the validated merged PrintTicket to see whether the 
// the validation process has kept the duplexing option we want to set unchanged. 

// 

if (result.ValidatedPrintTicket.Duplexing == Duplexing.TwoSidedLongEdge) 

{ 

// 

// Set the printer's user-default PrintTicket and commit the set operation. 

// 

queue.UserPrintTicket = result.ValidatedPrintTicket; 
queue.CommitO; 

Console.WriteLine("PrintTicket new duplexing setting is set on '{0}'.", queue.FullName); 

} 

else 

{ 

// 

// The duplexing option we want to set has been changed by the validation process 
// when it was resolving setting constraints. 

// 

Console.WriteLine("PrintTicket new duplexing setting is constrained on '{0}'.", queue.FullName) 

} 

} 

else 

{ 

// 

// If the printer doesn't support the duplexing option we want to set, skip it. 

// 

Console.WriteLine("PrintTicket new duplexing setting is not supported on '{0}'.", queue.FullName); 



' '' <summary> 

''' Changes the user-default PrintTicket setting of the specified print queue. 

' ' ' </summary> 

''' <param name="queue">the printer whose user-default PrintTicket setting needs to be changed</param> 

Private Shared Sub ChangePrintTicketSetting(ByVal queue As PrintQueue) 

' Obtain the printer's PrintCapabilities so we can determine whether or not 
' duplexing printing is supported by the printer. 

Dim printcap As PrintCapabilities = queue.GetPrintCapabilities() 

' The printer's duplexing capability is returned as a read-only collection of duplexing options 
' that can be supported by the printer. If the collection returned contains the duplexing 
' option we want to setj it means the duplexing option we want to set is supported by the printer^ 

' so we can make the user-default PrintTicket setting change. 

If printcap.DuplexingCapability.Contains(Duplexing.TwoSidedLongEdge) Then 

' To change the user-default PrintTicketj we can first create a delta PrintTicket with 
' the new duplexing setting. 

Dim deltaTicket As New PrintTicket() 
deltaTicket.Duplexing = Duplexing.TwoSidedLongEdge 

' Then merge the delta PrintTicket onto the printer's current user-default PrintTicket, 

' and validate the merged PrintTicket to get the new PrintTicket we want to set as the 
' printer's new user-default PrintTicket. 

Dim result As ValidationResult = queue.MergeAndValidatePrintTicket(queue.LlserPrintTicket, deltaTicket) 

' The duplexing option we want to set could be constrained by other PrintTicket settings 
' or device settings. We can check the validated merged PrintTicket to see whether the 
' the validation process has kept the duplexing option we want to set unchanged. 

If result.ValidatedPrintTicket.Duplexing = Duplexing.TwoSidedLongEdge Then 

' Set the printer's user-default PrintTicket and commit the set operation. 

queue.UserPrintTicket = result.ValidatedPrintTicket 
queue.CommitO 

Console.WriteLine("PrintTicket new duplexing setting is set on '{0}'.", queue.FullName) 

Else 

' The duplexing option we want to set has been changed by the validation process 
' when it was resolving setting constraints. 

Console.WriteLine("PrintTicket new duplexing setting is constrained on '{0}'.", queue.FullName) 

End If 

Else 

' If the printer doesn't support the duplexing option we want to set, skip it. 

Console.WriteLine("PrintTicket new duplexing setting is not supported on '{0}'.", queue.FullName) 

End If 
End Sub 


So that you can quickly test this example, the remainder of it is presented below. Create a project and a namespace 
and then paste both the code snippets in this article into the namespace block. 

Ill <summary> 

III Displays the correct command line syntax to run this sample program. 

Ill </summary> 

static nrivate void Di snl avUsapet'1 






{ 

Console.WniteLineO; 

Console.WriteLine("Usage #1: printticket.exe -1 \"<pninter_name>\"")j 
Console.WriteLine(" Run program on the specified local printer"); 

Console.WriteLineO; 

Console.WriteLine(" Quotation marks may be omitted if there are no spaces in printer_name.") 

Console.WriteLineO; 

Console.WriteLine("Usage #2: printticket.exe -r \"\\\\<server_name>\\<printer_name>\""); 

Console.WriteLine(" Run program on the specified network printer"); 

Console.WriteLineO > 

Console.WriteLine(" Quotation marks may be omitted if there are no spaces in server_name or 

printer_name."); 

Console.WriteLineO > 

Console.WriteLineC'Usage #3: printticket.exe -a"); 

Console.WriteLine(" Run program on all installed printers"); 

Console. WriteLineO; 

} 

[STAThread] 

static public void Main(string[] args) 

{ 

try 

{ 

if ((args.Length == 1) && (args[0] == "-a")) 

{ 

// 

// Change PrintTicket setting for all local and network printer connections. 

// 

LocalPrintServer server = new LocalPrintServerO; 

EnumeratedPrintQueueTypes[] queue_types = {EnumeratedPrintQueueTypes.Localj 

EnumeratedPrintQueueTypes.Connections}; 


// 

// Enumerate through all the printers. 

// 

foreach (PrintQueue queue in server.GetPrintQueues(queue_types)) 

{ 

// 

// Change the PrintTicket setting queue by queue. 

// 

ChangePrintTicketSetting(queue); 

} 

}//end if -a 

else if ((args.Length == 2) && (args[0] == "-!")) 

{ 

// 

// Change PrintTicket setting only for the specified local printer. 

// 

LocalPrintServer server = new LocalPrintServerO; 

PrintQueue queue = new PrintQueue(serverj args[l]); 
ChangePrintTicketSetting(queue); 

}//end if -1 

else if ((args.Length == 2) && (args[0] == "-r")) 

{ 

// 

// Change PrintTicket setting only for the specified remote printer. 

// 

String serverName = args[l].Remove(args[l].LastIndexOf(@"\")); 

String printerName = args[l].Remove(0, args[l].LastIndexOf(@"\")+l); 
PrintServer ps = new PrintServer(serverName); 

PrintQueue queue = new PrintQueue(pSj printerName); 
ChangePrintTicketSetting(queue); 

}//end if -r 


else 


// 

// Unrecognized command line. 

// Show user the correct command line syntax to run this sample program. 

// 

DisplayUsageO; 

} 

} 

catch (Exception e) 

{ 

Console.WriteLine(e.Message); 

Console.WriteLine(e.StackTrace); 

// 

// Show inner exception information if it's provided. 

// 

if (e.InnerException != null) 

{ 

Console.WriteLine("— Inner Exception —"); 

Console.WriteLine(e.InnerException.Message); 

Console.WriteLine(e.InnerException.StackTrace); 

} 

} 

finally 

{ 

Console.WriteLineC’Press Return to continue..."); 

Console.ReadLlneO; 

} 

}//end Main 


<summary> 

''' Displays the correct command line syntax to run this sample program. 

''' </summary> 

Private Shared Sub DisplayUsage() 

Console.WriteLineO 

Console.WriteLine("Usage #1: printticket.exe -1 ""<printer_name>""") 

Console.WriteLine(" Run program on the specified local printer") 

Console.WriteLineO 

Console.WriteLine(" Quotation marks may be omitted if there are no spaces in printer_name 

Console.WriteLineO 

Console.WriteLine("Usage #2: printticket.exe -r ""\\<server_name>\<printer_name>""") 
Console.WriteLine(" 

Console.WriteLineO 
Console.WriteLine(" 
printer_name.") 

Console.WriteLineO 

Console.WriteLine("Usage #3: printticket.exe -a") 

Console.WriteLine(" Run program on all installed printers") 

Console.WriteLineO 
End Sub 


Run program on the specified network printer") 

Quotation marks may be omitted if there are no spaces in server_name or 


<STAThread> 

Public Shared Sub Main(ByVal argsO As String) 

Try 

If (args.Length = 1) AndAlso (args(0) = "-a") Then 

' Change PrintTicket setting for all local and network printer connections. 

Dim server As New LocalPrintServerO 

Dim queue_typesO As EnumeratedPrintQueueTypes = {EnumeratedPrintQueueTypes.Local, 
EnumeratedPrintQueueTypes.Connections} 


' Enumerate through all the printers. 
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' Change the PrintTicket setting queue by queue. 

ChangePnintTicketSetting(queue) 

Next queue 'end if -a 

Elself (angs.Length = 2) AndAlso (args(0) = "-1") Then 

' Change PrintTicket setting only for the specified local printer. 

Dim server As New LocalPrintServer() 

Dim queue As New PrintQueue(serverj args(l)) 
ChangePrintTicketSetting(queue) 'end if -1 

Elself (args.Length = 2) AndAlso (args(0) = "-r") Then 

' Change PrintTicket setting only for the specified remote printer. 

Dim serverName As String = args(l).Remove(args(l).LastIndexOf("\")) 

Dim printerName As String = args(l).Remove(0j args(l).LastIndexOf("\")+l) 
Dim ps As New PrintServer(serverName) 

Dim queue As New PrintQueue(pSj printerName) 
ChangePrintTicketSetting(queue) 'end if -r 

Else 

' Unrecognized command line. 

' Show user the correct command line syntax to run this sample program. 

DisplayUsageO 
End If 

Catch e As Exception 

Console.WriteLine(e.Message) 

Console.WriteLine(e.StackTrace) 

' Show inner exception information if it's provided. 

If e.InnerException IsNot Nothing Then 

Console.WriteLine("— Inner Exception —") 

Console. WriteLine(e. Inner Except ion .Message) 

Console.WriteLine(e.InnerException.StackTrace) 

End If 
Finally 

Console.WriteLine("Press Return to continue...") 

Console.ReadLineO 
End Try 
End Sub 


See also 

• PrintCapabilities 

• PrintTicket 

• GetPrintQueues 

• PrintServer 

• EnumeratedPrintQueueTypes 

• PrintQueue 

• GetPrintCapabilities 

• Documents in WPF 

• Printing Overview 

• Print Schema 
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Windows Presentation Foundation (WPF) provides extensive support for the development of world-ready 
applications. 

In This Section 

WPF Globalization and Localization Overview 
Globalization for WPF 
Use Automatic Layout Overview 
Localization Attributes and Comments 
Bidirectional Features in WPF Overview 
Flow-to Topics 

Reference 

System.Globalization 
FlowDirection 

Neutral ResourcesLanguageAttribute 
xmLIang Flandling in XAML 
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WPF Globalization and Localization Overview 

8/17/2020 • 15 minutes to read ^ Edit Online 


When you limit your product's availability to only one language, you limit your potential customer base to a 
fraction of our world's 7.5 billion population. If you want your applications to reach a global audience, cost- 
effective localization of your product is one of the best and most economical ways to reach more customers. 

This overview introduces globalization and localization in Windows Presentation Foundation (WPF). Globalization 
is the design and development of applications that perform in multiple locations. For example, globalization 
supports localized user interfaces and regional data for users in different cultures. WPF provides globalized design 
features, including automatic layout, satellite assemblies, and localized attributes and commenting. 

Localization is the translation of application resources into localized versions for the specific cultures that the 
application supports. When you localize in WPF, you use the APIs in the System.Windows.Markup.Localizer 
namespace. These APIs power the LocBamI Tool Sample command-line tool. For information about how to build 
and use LocBamI, see Localize an Application. 

Best Practices for Globalization and Localization in WPF 

You can make the most of the globalization and localization functionality that is built into WPF by following the Ul 
design and localization-related tips that this section provides. 

Best Practices for WPF Ul Design 

When you design a WPF-based Ul, consider implementing these best practices: 

• Write your Ul in XAML; avoid creating Ul in code. When you create your Ul by using XAML, you expose it 
through built-in localization APIs. 

• Avoid using absolute positions and fixed sizes to lay out content; instead, use relative or automatic sizing, 
o Use SizeToContent and keep widths and heights set to Auto . 

o Avoid using Canvas to lay out Uls. 
o Use Grid and its size-sharing feature. 

• Provide extra space in margins because localized text often requires more space. Extra space allows for 
possible overhanging characters. 

• Enable TextWrapping on TextBlock to avoid clipping. 

• Set the xmi:iang attribute. This attribute describes the culture of a specific element and its child elements. 

The value of this property changes the behavior of several features in WPF. For example, it changes the 
behavior of hyphenation, spell checking, number substitution, complex script shaping, and font fallback. See 
Globalization for WPF for more information about setting the xmLIang Handling in XAML. 

• Create a customized composite font to obtain better control of fonts that are used for different languages. 

By default, WPF uses the GlobalUserInterface.composite font in your Windows\Fonts directory. 

• When you create navigation applications that may be localized in a culture that presents text in a right-to- 
left format, explicitly set the FlowDirection of every page to ensure the page does not inherit FlowDirection 
from the NavigationWindow. 

• When you create stand-alone navigation applications that are hosted outside a browser, set the StartupUri 






for your initial application to a NavigationWindow instead of to a page (for example, 

<Appiication star'tupUri="NavigationWindow.xami"> ). This design enables you to change the FlowDirection of 
the Window and the navigation bar. For more information and an example, see Globalization Homepage 
Sample. 

Best Practices for WPF Localization 

When you localize WPF-based applications, consider implementing these best practices: 

• Use localization comments to provide extra context for localizers. 

• Use localization attributes to control localization instead of selectively omitting Uid properties on elements. 
See Localization Attributes and Comments for more information. 

• Use msbuiid -t:updateuid and -t:checkuid to add and check Uid properties in your XAML. Use Uid 
properties to track changes between development and localization. Uid properties help you localize new 
development changes. If you manually add Uid properties to a Ul, the task is typically tedious and less 
accurate. 

o Do not edit or change Uid properties after you begin localization. 

o Do not use duplicate Uid properties (remember this tip when you use the copy-and-paste 
command). 

o Set the uitimateResourceFaiiback location in Assemblyinfo.* to specify the appropriate language for 
fallback (for example. 



Localize a WPF Application 

When you localize a WPF application, you have several options. For example, you can bind the localizable 

resources in your application to an XML file, store localizable text in resx tables, or have your localizer use 

Extensible Application Markup Language (XAML) files. This section describes a localization workflow that uses the 

BAML form of XAML, which provides several benefits: 

• You can localize after you build. 

• You can update to a newer version of the BAML form of XAML with localizations from an older version of 
the BAML form of XAML so that you can localize at the same time that you develop. 

• You can validate original source elements and semantics at compile time because the BAML form of XAML 
is the compiled form of XAML. 

Localization Build Process 

When you develop a WPF application, the build process for localization is as follows: 

• The developer creates and globalizes the WPF application. In the project file the developer sets 

<uicuitur'e>en-us</uicuiture> SO that when the application is compiled, a language-neutral main assembly 
is generated. This assembly has a satellite .resources.dll file that contains all the localizable resources. 
Optionally, you can keep the source language in the main assembly because our localization APIs support 
extraction from the main assembly. 

• When the file is compiled into the build, the XAML is converted to the BAML form of XAML. The culturally 









neutral MyDiaiog.exe and the culturally dependent (English) MyDiaiog.resources.dll files are released to 
the English-speaking customer. 

Localization Workflow 

The localization process begins after the unlocalized MyDiaiog.resources.dll file is built. The Ul elements and 
properties in your original XAML are extracted from the BAML form of XAML into key-value pairs by using the 
APIs under System.Windows.Markup.Localizer. Localizers use the key-value pairs to localize the application. You 
can generate a new .resource.dll from the new values after localization is complete. 

The keys of the key-value pairs are x:Uid values that are placed by the developer in the original XAML. These 
x:uid values enable the API to track and merge changes that happen between the developer and the localizer 
during localization. For example, if the developer changes the Ul after the localizer begins localizing, you can 
merge the development change with the already completed localization work so that minimal translation work is 
lost. 


The following graphic shows a typical localization workflow that is based on the BAML form of XAML. This diagram 
assumes the developer writes the application in English. The developer creates and globalizes the WPF application. 
In the project file the developer sets <uicuitune>en-us</uicuiture> so that on build, a language neutral main 
assembly gets generated with a satellite .resources.dll containing all localizable resources. Alternately, one could 
keep the source language in the main assembly because WPF localization APIs support extraction from the main 
assembly. After the build process, the XAML get compiled into BAML. The culturally neutral 
MyDialog.exe.resources.dll get shipped to the English speaking customer. 
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Examples of WPF Localization 

This section contains exannples of localized applications to help you understand how to build and localize WPF 
applications. 


Run Dialog Box Example 

The following graphics show the output of the Run dialog box sample. 
English; 



German: 



Designing a Global Run Dialog Box 

This example produces a Run dialog box by using WPF and XAML. This dialog box is equivalent to the Run dialog 
box that is available from the Microsoft Windows Start menu. 























































Some highlights for making global dialog boxes are: 
Automatic Layout 
In Window!.xanni: 


<Window SizeToContent="WidthAndHeight"> 

The previous Window property automatically resizes the window according to the size of the content. This 
property prevents the window from cutting off content that increases in size after localization; it also removes 
unneeded space when content decreases in size after localization. 

<Gr'id x:Uid="Gr'id_l"> 

Did properties are needed in order for WPF localization APIs to work correctly. 

They are used by WPF localization APIs to track changes between the development and localization of the user 
interface (Ul). Uid properties enable you to merge a newer version of the Ul with an older localization of the Ul. You 
add a Uid property by running msbuiid -tiupdateuid Runoiaiog.csproj in a command shell. This is the 
recommended method of adding Uid properties because manually adding them is typically time-consuming and 
less accurate. You can check that Uid properties are correctly set by running msbuiid -t:checkuid RunOiaiog.csproj . 

The Ul is structured by using the Grid control, which is a useful control for taking advantage of the automatic 
layout in WPF. Note that the dialog box is split into three rows and five columns. Not one of the row and column 
definitions has a fixed size; hence, the Ul elements that are positioned in each cell can adapt to increases and 
decreases in size during localization. 

<Gr'id. ColumnDef initions> 

<ColumnDefinition x:Uid="ColumnDefinition_l" /> 

<ColumnDefinition x:Uid="ColumnDefinition_2" /> 

The first two columns where the Open: label and ComboBox are placed use 10 percent of the Ul total width. 

<ColumnDefinition x:Uid="ColumnDefinition_3" SharedSizeGroup="Buttons" /> 

<ColumnDefinition x:Uid="ColumnDefinition_4" SharedSizeGroup="Buttons" /> 

<ColumnDefinition x:Uid="ColumnDefinition_5" SharedSizeGroup="Buttons" /> 

</Grid.ColumnDefinitions> 

Note that of the example uses the shared-sizing feature of Grid. The last three columns take advantage of this by 
placing themselves in the same SharedSizeGroup. As one would expect from the name of the property, this allows 
the columns to share the same size. So when the "Browse..." gets localized to the longer string "Durchsuchen...", all 
buttons grow in width instead of having a small "OK" button and a disproportionately large "Durchsuchen..." 
button. 

xmhiang 

xml:lang="en-US" 

Notice the xmLIang Handling in XAML placed at the root element of the Ul. This property describes the culture of a 
given element and its children. This value is used by several features in WPF and should be changed appropriately 
during localization. This value changes what language dictionary is use to hyphenate and spell check words. It also 
affects the display of digits and how the font fallback system selects which font to use. Finally, the property affects 
the way numbers are displayed and the way texts written in complex scripts are shaped. The default value is "en- 
US". 


Building a Satellite Resource Assembly 


In .csproj: 








Editthe .cspnoj file and add the following tag to an unconditional <PropertyGroup> : 

<LIICultur'e>en-US</UICulture> 

Notice the addition of a uicuiture value. When this is set to a valid Cultureinfo value such as en-US, building the 
project will generate a satellite assembly with all localizable resources in it. 

<Resource Include="RunIcon.DPG"> 

<Localizable>False</Localizable> 

</Resource> 

The Runicon.DPG does not need to be localized because it should appear the Same for all Cultures. Localizable is 
set to false so that it remains in the language neutral main assembly instead of the satellite assembly. The default 
value of all noncompilable resources is Localizable set to true. 

Localizing the Run Dialog 

Parse 

After building the application, the first step in localizing it is parsing the localizable resources out of the satellite 
assembly. For the purposes of this topic, use the sample LocBamI tool which can be found at LocBamI Tool Sample. 
Note that LocBamI is only a sample tool meant to help you get started in building a localization tool that fits into 
your localization process. Using LocBamI, run the following to parse: LocBamI /parse RunDialog.resources.dll 
/out: to generate a "RunDialog.resources.dll.CSV" file. 

Localize 

Use your favorite CSV editor that supports Unicode to edit this file. Filter out all entries with a localization category 
of "None". You should see the following entries: 


RESOURCE KEY 

LOCALIZATION CATEGORY 

VALUE 

Button_1:System.Windows.Controls.But 

ton.$Content 

Button 

OK 

Button_2:System.Windows.Controls.But 

ton.$Content 

Button 

Cancel 

Button_3:System.Windows.Controls.But 

ton.$Content 

Button 

Browse... 

ComboBox_1:System.Windows.Controls 

.ComboBox.$Content 

ComboBox 


TextBlock_1:System.Windows.Controls.T 

extBlock.$Content 

Text 

Type the name of a program, folder, 
document, or Internet resource, and 
Windows will open it for you. 

TextBlock_2:System.Windows.Controls.T 

extBlock.$Content 

Text 

Open: 

Window_1 :System.Windows.Window.Titl 

Title 

Run 


e 


Localizing the application to German would require the following translations: 













RESOURCE KEY 


LOCALIZATION CATEGORY 


VALUE 


Button_1 :System.Windows.Controls.But 
ton.$Content 

Button 

OK 

Button_2:System.Windows.Controls.But 

ton.$Content 

Button 

Abbrechen 

Button_3:System.Windows.Controls.But 

ton.$Content 

Button 

Durchsuchen... 

ComboBox_1:System.Windows.Controls 

.ComboBox.$Content 

ComboBox 


TextBlock_1:System.Windows.Controls.T 

extBlock.$Content 

Text 

Geben Sie den Namen eines 
Programms, Ordners, Dokuments oder 
einer Internetresource an. 

TextBlock_2:System.Windows.Controls.T 

extBlock.$Content 

Text 

Offnen: 

Window_1 :System.Windows.Window.Titl 

e 

Title 

Run 

Generate 



The last step of localization involves creating the newly localized satellite assembly. This can be accomplished with 
the following LocBamI command: 

LocBaml.exe /generate RunDialog.resources.dll /trans:RunDialog.resources.dll.CSV /out; . /cul;de-DE 

On German Windows, if this resources.dll is placed in a de-DE folder next to the main assembly, this resource will 
automatically load instead of the one in the en-US folder. If you do not have a German version of Windows to test 

this, set the culture to whatever culture of Windows you are using (for example. 

en-US ), and replace the original 

resources DLL. 



Satellite Resource Loading 



MYDIALOG.EXE 

EN-US\MYDIALOG.RESOURCES.DLL 

DE-DE\MYDIALOG.RESOURCES.DLL 

Code 

Original English BAML 

Localized BAML 

Culturally neutral resources 

Other resources in English 

Other resources localized to German 


•NET automatically chooses which satellite resources assembly to load based on the application's 
Thread.CurrentUICulture. This defaults to the culture of your Windows OS. If you're using German Windows, the 
cle-DE\MyDialog.resources.clllY\\e loads. If you're using English Windows, the en-US\MyDialog.resources.dll f\\e 
loads. You can set the ultimate fallback resource for your application by specifying the NeutraiResourcesLanguage 
attribute in your project's Assembly In fof\\e. For example, if you specify: 

[assembly: NeutralResourcesLanguage("en-US"j UltimateResourceFallbackLocation.Satellite)] 

then the en-US\MyDlalog.resources.dllY\\e is used with German Windows if neither of the following files are 
available: de-DE\MyDlalog.resources.dll or de\MyDialog.resources.dll 

Microsoft Saudi Arabia Homepage 

The following graphics show an English and Arabic Homepage. For the complete sample that produces these 




graphics see Globalization Homepage Sample. 


English; 



Arabic: 





























Designing a Global Microsoft home page 

This mock up of the Microsoft Saudi Arabia web site illustrates the globalization features provided for RightToLeft 
languages. Languages such as Hebrew and Arabic have a right-to-left reading order so the layout of Ul must often 
be laid out quite differently than it would be in left-to-right languages such as English. Localizing from a left-to- 
right language to a right-to-left language or vice versa can be quite challenging. WPF has been designed to make 
such localizations much easier. 

FlowDirection 

Homepage.xamI: 

<Page X:Uid="Page_l" x:Class="MicrosoftSaudiArabiaHomepage.Homepage" 
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

FlowDir'ection="LeftToRight" 

Localization.Comments="FlowDirection(This FlowDirection controls the actual content of the homepage)" 
xml: lang="en-LIS"> 


Notice the FlowDirection property on Page. Changing this property to RightToLeft will change the FlowDirection of 
the Page and its children elements so that the layout of this Ul is flipped to become right-to-left as an Arabic user 
would expect. One can override the inheritance behavior by specifying an explicit FlowDirection on any element. 
The FlowDirection property is available on any FrameworkElement or document related element and has an 
implicit value of LeftToRight. 

Observe that even the background gradient brushes are flipped correctly when the root FlowDirection is changed: 


F low Direction = " LeftToRight" 































FlowDirection = "RightToLeft" 



Avoid Using Fixed Dimensions for Panels and Controls 

Take a look through Homepage.xamI, notice that aside from the fixed width and height specified for the entire Ul 
on the top DockPanel, there are no other fixed dimensions. Avoid using fixed dimensions to prevent clipping 
localized text that may be longer than the source text. WPF panels and controls will automatically resize based on 
the content that they contain. Most controls also have minimum and maximum dimensions that you can set for 
more control (for example, MinWidth = "20"). With Grid, you can also set relative widths and heights by using 
(for example, width="0.25*" ) or use its cell size sharing feature. 

Localization Comments 

There are many cases where content may be ambiguous and difficult to translate. The developer or designer has 
the ability to provide extra context and comments to localizers through localization comments. For example the 
Localization.Comments below clarifies the usage of the character '|'- 

<TextBlock 

x:Uid="TextBlock_2" 

DockPanel.Dock="Right" 

Foreground="White" 

Mar'gin="5,0,5,0" 

Localization.Comments="$Content(This character is used as a decorative rule.)"> 

I 

</TextBlock> 


This comment becomes associated with TextBlock_1 's content and in the case of the LocBamI Tool, ( see Localize an 
Application), it can be seen in the 6th column of the TextBlock_1 row in the output .csv file: 

RESOURCE KEY CATEGORY READABLE MODIFIABLE COMMENT VALUE 

TextBlock_1 :Syste Text TRUE TRUE This character is | 

m.Windows.Cont used as a 

rols.TextBlock.$C decorative rule, 

ontent 


Comments can be placed on the content or property of any element using the following syntax: 

<TextBlock 

x:Uid="TextBlock_l" 

DockPanel.Dock="Right" 

Foreground="White" 

Margin="5,0,5,0" 

Localization.Comments="$Content(This is a comment on the TextBlock's content.) 

Margin(This is a comment on the TextBlock's Margin property.)"> 

I 

</TextBlock> 


Localization Attributes 














Often the developer or localization manager needs control of what localizers can read and modify. For example, 
you might not want the localizer to translate the name of your company or legal wording. WPF provides attributes 
that enable you to set the readability, modifiability, and category of an element's content or property which your 
localization tool can use to lock, hide, or sort elements. For more information, see Attributes. For the purposes of 
this sample, the LocBamI Tool just outputs the values of these attributes. WPF controls all have default values for 
these attributes, but you the can override them. For example, the following example overrides the default 
localization attributes for TextBiock_i and sets the content to be readable but unmodifiable for localizers. 

<TextBlock 

x:Uid="TextBlock_l" 

Localization.Attributes= 

"$Content(Readable Unmodifiable)"> 

Microsoft Corporation 
</TextBlock> 


In addition to the readability and modifiability attributes, WPF provides an enumeration of common Ul categories 
(LocalizationCategory) that can be used to give localizers more context. The WPF default categories for platform 
controls can be overridden in XAML as well: 


<TextBlock x:Uid="TextBlock_2"> 

<TextBlock.ToolTips 

<TextBlock 

x:Uid="TextBlock_3" 

Localization.Attributes= 

"$Content(ToolTip Readable Unmodifiable)"> 

Microsoft Corporation 

</TextBlock> 

</TextBlock.ToolTips 
Windows Vista 
</TextBlocks 


The default localization attributes that WPF provides can also be overridden through code, so you can correctly set 
the right default values for custom controls. For example: 

[Localizability(Readability = Readability.Readable, Modifiability=Modiflability.Unmodifiable, 
LocalizationCategory.None)] 
public class CorporateLogo : TextBlock 
{ 

n ... 

} 


The per instance attributes set in XAML will take precedence over the values set in code on custom controls. For 
more information on attributes and comments, see Localization Attributes and Comments. 

Font Fallback and Composite Fonts 

If you specify a font that does not support a given codepoint range, WPF will automatically fallback to one that 
does by using the Global User Interface.compositefont that is located in your Windows\Fonts directory. Composite 
fonts work just as any other font and can be used explicitly by setting an element's FontFamiiy (for instance, 
FontFamiiy="Giobai User Interface" ). You can specify your own font fallback preference by creating your own 
composite font and specifying what font to use for specific codepoint ranges and languages. 

For more information on composite fonts see FontFamiiy. 

Localizing the Microsoft Homepage 

You can follow the same steps as the Run Dialog example to localize this application. The localized .csv file for 
Arabic is available for you in the Globalization Homepage Sample. 
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This topic introduces issues that you should be aware of when writing Windows Presentation Foundation (WPF) 
applications for the global market. The globalization programming elements are defined in .NET in the 
System.Globalization namespace. 

XAML Globalization 

Extensible Application Markup Language (XAML) is based on XML and takes advantage of the globalization 
support defined in the XML specification. The following sections describe some XAML features that you should be 
aware of 

Character References 

A character reference gives the UTF16 code unit of the particular Unicode character it represents, in either decimal 
or hexadecimal. The following example shows a decimal character reference for the COPTIC CAPITAL LETTER HORI, 
or '8': 

&# 1000 ; 

The following example shows a hexadecimal character reference. Notice that it has an x in front of the hexadecimal 
number. 

&#x3E8; 

Encoding 

The encoding supported by XAML are ASCII, Unicode UTF-16, and UTF-8. The encoding statement is at the 
beginning of XAML document. If no encoding attribute exists and there is no byte-order, the parser defaults to 
UTF-8. UTF-8 and UTF-16 are the preferred encodings. UTF-7 is not supported. The following example 
demonstrates how to specify a UTF-8 encoding in a XAML file. 

?xml encoding="LITF-8"? 

Language Attribute 

XAML uses xmLIang to represent the language attribute of an element. To take advantage of the Cultureinfo class, 
the language attribute value needs to be one of the culture names predefined by Cultureinfo. xmLIang is 
inheritable in the element tree (by XML rules, not necessarily because of dependency property inheritance) and its 
default value is an empty string if it is not assigned explicitly. 

The language attribute is very useful for specifying dialects. For example, French has different spelling, vocabulary, 
and pronunciation in France, Quebec, Belgium, and Switzerland. Also Chinese, Japanese, and Korean share code 
points in Unicode, but the ideographic shapes are different and they use totally different fonts. 

The following Extensible Application Markup Language (XAML) example uses the fr-CA language attribute to 
specify Canadian French. 

<TextBlock xml:lang="fr'-CA">Decouvr'ir' la France</TextBlock> 







Unicode 

XAML supports all Unicode features including surrogates. As long as the character set can be mapped to Unicode, 
it is supported. For example, GB18030 introduces some characters that are mapped to the Chinese, Japanese, and 
Korean (CFK) extension A and B and surrogate pairs, therefore it is fully supported. A WPF application can use 
Stringinfo to manipulate strings without understanding whether they have surrogate pairs or combining 
characters. 

Designing an International User Interface with XAML 

This section describes user interface (Ul) features that you should consider when writing an application. 

International Text 

WPF includes built-in processing for all Microsoft .NET Framework supported writing systems. 

The following scripts are currently supported; 

• Arabic 

• Bengali 

• Devanagari 

• Cyrillic 

• Greek 

• Gujarati 

• Gurmukhi 

• Hebrew 

• Ideographic scripts 

• Kannada 

• Lao 

• Latin 

• Malayalam 

• Mongolian 

• Odia 

• Syriac 

• Tamil 

• Telugu 

• Thaana 

• Thai* 

• Tibetan 

*ln this release the display and editing of Thai text is supported; word breaking is not. 

The following scripts are not currently supported: 


• Khmer 



• Korean Old Hangul 

• Myanmar 

• Sinhala 

All the writing system engines support OpenType fonts. OpenType fonts can include the OpenType layout tables 
that enable font creators to design better international and high-end typographic fonts. The OpenType font layout 
tables contain information about glyph substitutions, glyph positioning, justification, and baseline positioning, 
enabling text-processing applications to improve text layout. 

OpenType fonts allow the handling of large glyph sets using Unicode encoding. Such encoding enables broad 
international support as well as for typographic glyph variants. 

WPF text rendering is powered by Microsoft ClearType sub-pixel technology that supports resolution 
independence. This significantly improves legibility and provides the ability to support high quality magazine style 
documents for all scripts. 

International Layout 

WPF provides a very convenient way to support horizontal, bidirectional, and vertical layouts. In presentation 
framework the FlowDirection property can be used to define layout. The flow direction patterns are: 

• LeftToRight- horizontal layout for Latin, East Asian and so forth. 

• RightToLeft- bidirectional for Arabic, Hebrew and so forth. 

Developing Localizable Applications 

When you write an application for global consumption you should keep in mind that the application must be 
localizable. The following topics point out things to consider. 

Multilingual User Interface 

Multilingual User Interfaces (MUI) is a Microsoft support for switching Uls from one language to another. A WPF 
application uses the assembly model to support MUI. One application contains language-neutral assemblies as 
well as language-dependent satellite resource assemblies. The entry point is a managed .EXE in the main 
assembly. WPF resource loader takes advantage of the Framework's resource manager to support resource 
lookup and fallback. Multiple language satellite assemblies work with the same main assembly. The resource 
assembly that is loaded depends on the CurrentUICulture of the current thread. 

Localizable User Interface 

WPF applications use XAML to define their Ul. XAML allows developers to specify a hierarchy of objects with a set 
of properties and logic. The primary use of XAML is to develop WPF applications but it can be used to specify a 
hierarchy of any common language runtime (CLR) objects. Most developers use XAML to specify their 
application's Ul and use a programming language such as C# to react to user interaction. 

From a resource point of view, a XAML file designed to describe a language-dependent Ul is a resource element 
and therefore its final distribution format must be localizable to support international languages. Because XAML 
cannot handle events many XAML applications contain blocks of code to do this. For more information, see XAML 
Overview (WPF). Code is stripped out and compiled into different binaries when a XAML file is tokenized into the 
BAML form of XAML. The BAML form of XAML files, images, and other types of managed resource objects are 
embedded in the satellite resource assembly, which can be localized into other languages, or the main assembly 
when localization is not required. 


NOTE 

WPF applications support all the FrameworkCLR resources including string tables, images, and so forth. 



Building Localizable Applications 

Localization means to adapt a Ul to different cultures. To make a WPF application localizable, developers need to 
build all the localizable resources into a resource assembly. The resource assembly is localized into different 
languages, and the code-behind uses resource management API to load. One of the files required for a WPF 
application is a project file (.proj). All resources that you use in your application should be included in the project 
file. The following example from a .csproj file shows how to do this. 

<Resource Include="data\picturel.jpg"/> 

<EmbeddedResource Include="data\stringtable.en-US.restext"/> 


To use a resource in your application instantiate a ResourceManager and load the resource you want to use. The 
following example demonstrates how to do this. 

void OnClick(object sendeCj RoutedEventArgs e) 

{ 

ResourceManager rm = new ResourceManager ("MySampleApp.data.stringtable", 

Assembly.GetExecutingAssembly()); 

Textl.Text = rm.GetStringC'Message"); 

} 


Using ClickOnce with Localized Applications 

ClickOnce is a new Windows Forms deployment technology that will ship with Visual Studio 2005. It enables 
application installation and upgrading of Web applications. When an application that was deployed with ClickOnce 
is localized it can only be viewed on the localized culture. For example, if a deployed application is localized to 
Japanese it can only be viewed on Japanese Microsoft Windows not on English Windows. This presents a problem 
because it is a common scenario for Japanese users to run an English version of Windows. 

The solution to this problem is setting the neutral language fallback attribute. An application developer can 
optionally remove resources from the main assembly and specify that the resources can be found in a satellite 
assembly corresponding to a specific culture. To control this process use the NeutralResourcesLanguageAttribute. 
The constructor of the NeutralResourcesLanguageAttribute class has two signatures, one that takes an 
UltimateResourceFallbackLocation parameter to specify the location where the ResourceManager should extract 
the fallback resources: main assembly or satellite assembly. The following example shows how to use the attribute. 
For the ultimate fallback location, the code causes the ResourceManager to look for the resources in the "de" 
subdirectory of the directory of the currently executing assembly. 

[assembly: NeutralResourcesLanguageAttr'ibute( 

"de" , UltimateResounceEallbackLocation.Satellite)] 


See also 


• WPF Globalization and Localization Overview 
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This topic introduces guidelines for developers on how to write Windows Presentation Foundation (WPF) 
applications with localizable user interfaces (Uls). In the past, localization of a Ul was a time consuming process. 
Each language that the Ul was adapted for required a pixel by pixel adjustment. Today with the right design and 
right coding standards, Uls can be constructed so that localizers have less resizing and repositioning to do. The 
approach to writing applications that can be more easily resized and repositioned is called automatic layout, and 
can be achieved by using WPF application design. 

Advantages of Using Automatic Layout 

Because the WPF presentation system is powerful and flexible, it provides the ability to layout elements in an 
application that can be adjusted to fit the requirements of different languages. The following list points out some 
of the advantages of automatic layout. 

• Ul displays well in any language. 

• Reduces the need to readjust position and size of controls after text is translated. 

• Reduces the need to readjust window size. 

• Ul layout renders properly in any language. 

• Localization can be reduced to the point that it is little more than string translation. 

Automatic Layout and Controls 

Automatic layout enables an application to adjust the size of a control automatically. For example, a control can 
change to accommodate the length of a string. This capability enables localizers to translate the string; they no 
longer need to resize the control to fit the translated text. The following example creates a button with English 
content. 


<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

X:Class="ButtonLoc.Panel" 

Name="myWindow" 

SizeToContent="WidthAndHeight" 

> 

<DockPanel> 

<Button FontSize="28" Height="50">My name is Hope.</Button> 
</DockPanel> 

</Window> 


In the example, all you have to do to make a Spanish button is change the text. For example. 





<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="ButtonLoc.Panel" 

Name="myWindow" 

SizeToContent="WidthAndHeight" 

> 

<DockPanel> 

<Button FontSize="28" Height="50">Me llamo Esperanza.</Button> 
</DockPanel> 

</Window> 


The following graphic shows the output of the code samples: 




My name is Hope. 

■ B®® 

Me llamo Esperanza. 


Automatic Layout and Coding Standards 

Using the automatic layout approach requires a set of coding and design standards and rules to produce a fully 
localizable Ul. The following guidelines will aid your automatic layout coding. 

Do not use absolute positions 

• Do not use Canvas because it positions elements absolutely. 

• Use DockPanel, StackPanel, and Grid to position controls. 

For a discussion about various types of panels, see Panels Overview. 

Do not set a fixed size for a window 

• Use Window.SizeToContent. For example: 

<StackPanel 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

X:Class="GridLoc.Panel" 


Add a FlowDirection 

• Add a FlowDirection to the root element of your application. 

WPF provides a convenient way to support horizontal, bidirectional, and vertical layouts. In presentation 
framework, the FlowDirection property can be used to define layout. The flow-direct!on patterns are: 

o FlowDirection.LeftToRight (LrTb) — horizontal layout for Latin, East Asian, and so forth. 

o FlowDirection.RightToLeft (RITb) — bidirectional for Arabic, Hebrew, and so forth. 

Use composite fonts instead of physical fonts 











• With composite fonts, the FontFamily property does not need to be localized. 

• Developers can use one of the following fonts or create their own. 

o Global User Interface 
o Global San Serif 
o Global Serif 

Add xmhiang 

• Add the xmiiiang attribute in the root element of your Ul, such as xmi:iang="en-us" for an English 
application. 

• Because composite fonts use xmi:iang to determine what font to use, set this property to support 
multilingual scenarios. 

Automatic Layout and Grids 

The Grid element, is useful for automatic layout because it enables a developer to position elements. A Grid control 
is capable of distributing the available space among its child elements, using a column and row arrangement. The 
Ul elements can span multiple cells, and it is possible to have grids within grids. Grids are useful because they 
enable you to create and position complex Ul. The following example demonstrates using a grid to position some 
buttons and text. Notice that the height and width of the cells are set to Auto; therefore, the cell that contains the 
button with an image adjusts to fit the image. 





<Gr'id IMame="grid" ShowGridLines ="false"> 
<Gr'id.ColumnDefinitions> 

<ColumnDefinition Width="Auto"/> 
<ColumnDefinition Width="*"/> 

</Grid.ColumnDefinitions> 

<Gr'id. RowDefinitions> 

<RowDefinition Height="Auto"/> 
<RowDefinition Height="Auto"/> 
<RowDefinition Height="Auto"/> 
<RowDefinition Height="Auto"/> 
<RowDefinition Height="Auto"/> 

</Grid.RowDefinitions> 


<TextBlock Margin="10, 10, 5, 5" Gr'id.Column="0" Grid.Row="0" FontSize="24">Grid 

</TextBlock> 

<TextBlock Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="l" FontSize="12" 

Grid.ColumnSpan="2">The following buttons and text are positioned using a Grid. 

</TextBlock> 

<Button Margin="10j 10j 5, 5" Grid.Column="0" Gnid.Row="2" Background="Pink" 
BorderBrush="Black" BorderThickness="10">Button 1 

</Button> 

<TextBlock Margin="10, 10, S, 5" Grid.Column="l" Grid.Row="2" FontSize="12" 

\/erticalAlignment="Center" TextWrapping="WrapWithOverflow">Sets the background 
color. 

</TextBlock> 

<Button Hargin="10, 10, 5, 5" Grid.Column="0" Grid.Row="3" Foreground="Red"> 

Button 2 

</Button> 

<TextBlock Margin="10, 10, 5, 5" Grid.Column="l" Grid.Row="3" FontSize="12" 

\/erticalAlignment="Center" TextWrapping="WrapWithOverflow">Sets the foreground 
color. 

</TextBlock> 

<Button Margln="10, 10, 5, 5" Grid.Column="0" Grid.Row="4"> 

<Image Source="data\flower.jpg"></Image> 

</Button> 

<TextBlock Margin="10, 10, 5, 5" Grid.Column="l" Grid.Row="4" FontSize="12" 
\/erticalAlignment="Center" TextWrapping="WrapWithOverflow">Adds an image as 
the button's content. 

</TextBlock> 

</Grid> 


The following graphic shows the grid produced by the previous code. 



Automatic Layout and Grids Using the IsSharedSizeScope Property 

A Grid element is useful in Realizable applications to create controls that adjust to fit content However, at times 
you want controls to maintain a particular size regardless of content For example, if you have "OK", "Cancel" and 
"Browse" buttons you probably do not want the buttons sized to fit the content In this case the 
Grid.IsSharedSizeScope attached property is useful for sharing the same sizing among multiple grid elements. The 
following example demonstrates how to share column and row sizing data between multiple Grid elements. 














<StackPanel Orientation="Hor'izontal" DockPanel.Dock="Top"> 

<Button Click="setTr'ue" Margin="0,0jl0jl0">Set IsShanedSizeScope="True"</Button> 
<Button Click="setFalse" Mar'gin="0,0jl0jl0">Set IsSharedSizeScope="False"</Button> 

</StackPanel> 

<StackPanel Orientation="Flor'izontal" DockPanel.Dock="Top"> 

<Grid ShowGr'idLines="True" Mar'gin="0,0,10j0"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition SharedSizeGroup="FirstColumn"/> 

<ColumnDefinition Shar'edSlzeGr'oup="SecondColumn"/> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition Fleight="Auto" SharedSizeGroup="Fir'stRow"/> 

</Gnid.RowDefinitions> 

<Rectangle Fill="Silver" Grid.Column="0" Grid.Row="0" Width="200" Fleight="100"/> 
<Rectangle Fill="Blue" Grid.Column="l" Gnid.Row="0" Width="150" Fleight="100"/> 

<TextBlock Grid.Column="0" Grid.Row="0" FontWeight="Bold">First Column</TextBlock> 
<TextBlock Grid.Column="l" Grid.Row="0" FontWeight="Bold">Second Column</TextBlock> 

</Gnid> 

<Grid ShowGnidLines="True"> 

<Grld.ColumnDefinitions> 

<ColumnDefinition SharedSizeGroup="FirstColumn"/> 

<ColumnDefinition SharedSizeGroup="SecondColumn"/> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition Fleight="Auto" SharedSizeGroup="Fir'stRow"/> 

</Grid.RowDefinitions> 

<Rectangle Fill="Silver" Grid.Column="0" Grid.Row="0"/> 

<Rectangle Fill="Blue" Grid.Column="l" Gnid.Row="0"/> 

<TextBlock Grid.Column="0" Grid.Row="0" FontWeight="Bold">First Column</TextBlock> 
<TextBlock Grid.Column="l" Grid.Row="0" FontWeight="Bold">Second Column</TextBlock> 

</Gnid> 

</StackPanel> 

<TextBlock Margin="10" DockPanel.Dock="Top" Name="txtl"/> 


NOTE 

For the complete code sample, see Share Sizing Properties Between Grids. 


See also 

• Globalization for WPF 

• Use Automatic Layout to Create a Button 

• Use a Grid for Automatic Layout 
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Windows Presentation Foundation (WPF) localization comments are properties, inside XAML source code, 
supplied by developers to provide rules and hints for localization. Windows Presentation Foundation (WPF) 
localization comments contain two sets of information: localizability attributes and free-form localization 
comments. Localizability attributes are used by the WPF Localization API to indicate which resources are to be 
localized. Free-form comments are any information that the application author wants to include. 

Localization Comments 

If markup application authors have requirements for specific elements in XAML, such as constraints on text length, 
font family, or font size, they can convey this information to localizers with comments in the XAML code. The 
process for adding comments to source code is as follows: 

1. Application developer adds localization comments to XAML source code. 

2. During the build process, you can specify in the .proj file whether to leave the free-form localization 
comments in the assembly, strip out part of the comments, or strip out all the comments. The stripped-out 
comments are placed in a separate file. You specify your option using a LocaiizationoirectivesToLocFiie 
tag, eg: 

<LocalizationDirectivesToLocFile> value </LocalizationDirectivesToLocFile> 

3. The values that can be assigned are: 

• None - Both comments and attributes stay inside the assembly and no separate file is generated. 

• CommentsOnly - Strips only the comments from the assembly and places them in the separate 
LocFile. 

• All - Strips both the comments and the attributes from the assembly and places them both in a 
separate LocFile. 

4. When localizable resources are extracted from BAML, the localizability attributes are respected by the BAML 
Localization API. 

5. Localization comment files, containing only free-form comments, are incorporated into the localization 
process at a later time. 

The following example shows how to add localization comments to a XAML file. 

<TextBlocl< x:Id = "text01" 

FontFamily = "Microsoft Sans Serif" 

FontSize = "12" 

Localization.Attributes = "$Content (Unmodifiable Readable Text) 

FontFamily (Unmodifiable Readable)" 

Localization.Comments = "$Content (Trademark) 

FontSize (Trademark font size)" > 













Microsoft 


</TextBlock> 


In the previous sample the Localization.Attributes section contains the localization attributes and the 
Localization.Comments section the free-form comments. The following tables show the attributes and comments 
and their meaning to the localizer. 

LOCALIZATION ATTRIBUTES MEANING 

$Content (Unmodifiable Readable Text) Contents of the TextBlock element cannot be modified. 

Localizers cannot change the word "Microsoft". The content is 
visible (Readable) to the localizer. The category of the content 
is text. 


FontFamily (Unmodifiable Readable) 


The font family property of the TextBlock element cannot be 
changed but it is visible to the localizer. 


LOCALIZATION FREE-EORM COMMENTS MEANING 

$Content (Trademark) The application author tells the localizer that the content in 

the TextBlock element is a trademark. 


FontSize (Trademark font size) The application author indicates that the font size property 

should follow the standard trademark size. 


Localizability Attributes 

The information in Localization.Attributes contains a list of pairs: the targeted value name and the associated 
localizability values. The target name can be a property name or the special $Content name. If it is a property 
name, the targeted value is the value of the property. If it is $Content, the target value is the content of the 
element. 

There are three types of attributes: 

• Category. This specifies whether a value should be modifiable from a localizer tool. See Category. 

• Readability. This specifies whether a localizer tool should read (and display) a value. See Readability. 

• Modifiability. This specifies whether a localizer tool allows a value to be modified. See Modifiability. 

These attributes can be specified in any order delimited by a space. In case duplicate attributes are specified, the 
last attribute will override former ones. For example, Localization.Attributes = "Unmodifiable Modifiable" sets 
Modifiability to Modifiable because it is the last value. 

Modifiability and Readability are self-explanatory. The Category attribute provides predefined categories that help 
the localizer when translating text. Categories, such as. Text, Label, and Title give the localizer information about 
how to translate the text. There are also special categories: None, Inherit, Ignore, and NeverLocalize. 

The following table shows the meaning of the special categories. 


CATEGORY 

MEANING 

None 

Targeted value has no defined category. 

Inherit 

Targeted value inherits its category from its parent. 




CATEGORY 


MEANING 


Ignore 


Targeted value is ignored in the localization process. Ignore 
affects only the current value. It will not affect child nodes. 


NeverLocalize 


Current value cannot be localized. This category is inherited 
by the children of an element. 


Localization Comments 

Localization.Comments contains free-form strings concerning the targeted value. Application developers can add 
information to give localizers hints about how the applications text should be translated. The format of the 
comments can be any string surrounded by Use '\' to escape characters. 

See also 

• Globalization for WPF 

• Use Automatic Layout to Create a Button 

• Use a Grid for Automatic Layout 

• Localize an Application 
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Unlike any other development platform, WPF has many features that support rapid development of bidirectional 
content, for example, mixed left to right and right to left data in the same document. At the same time, WPF creates 
an excellent experience for users who require bidirectional features such as Arabic and Hebrew speaking users. 

The following sections explain many bidirectional features together with examples illustrating how to achieve the 
best display of bidirectional content. Most of the samples use XAML, though you can easily apply the concepts to 
C# or Microsoft Visual Basic code. 

FlowDirection 

The basic property that defines the content flow direction in a WPF application is FlowDirection. This property can 
be set to one of two enumeration values, LeftToRight or RightToLeft. The property is available to all WPF elements 
that inherit from FrameworkElement. 

The following examples set the flow direction of a TextBox element. 

Left-to-right flow direction 

<TextBlock Background="Dar'kBlue" For'eground="LightBlue" 

FontSize="20" FlowDir'ection="LeftToRight"> 

This is a left-to-right TextBlock 
</TextBlock> 


Right-to-left flow direction 


<TextBlock Background="LightBlue" Foreground="DankBlue" 
FontSize="20" FlowDirection="RightToLeft"> 

This is a right-to-left TextBlock 
</TextBlock> 


The following graphic shows how the previous code renders. 


Q XamIPad 


f] Auto Parse ► Refresh (S> Courier New '’12 ” Ql-lide Editor 


This is a left-to-riqht TextBlock 


This is a right-to-left TextBlock 


An element within a user interface (Ul) tree will inherit the FlowDirection from its container. In the following 
example, the TextBlock is inside a Grid, which resides in a Window. Setting the FlowDirection for the Window 
implies setting it for the Grid and TextBlock as well. 

The following example demonstrates setting FlowDirection. 
















<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="FlowDirectionApp.Windowl" 

Title="BidiFeatures" Fleight="200" Width="700" 
FlowDirection="RightToLeft"> 

<Grid> 

<Grid.ColumnDefinitions> 

<ColumnDefinition/> 

<ColumnDefinition/> 

</Grid.ColumnDefinitions> 
cTextBlock Grid.Column="0" > 

This is a right-to-left TextBlock 
</TextBlock> 

<TextBlock Grid.Column="l" FlowDirection="LeftToRight"> 

This is a left-to-right TextBlock 
</TextBlock> 

</Grid> 

</Window> 


The top level Window has a RightToLeftFlowDirection, so all elements contained within it also inherit the same 
FlowDirection. For an element to override a specified FlowDirection it must add an explicit direction change such as 
the second TextBlock in the previous example which changes to LeftToRight. When no FlowDirection is defined, the 
default LeftToRight applies. 

The following graphic shows the output of the previous example: 



FlowDocu merit 

Many development platforms such as FITML, Win32 and Java provide special support for bidirectional content 
development. Markup languages such as HTML give content writers the necessary markup to display text in any 
required direction, for example the HTML 4.0 tag, "dir" that takes "rtl" or "Itr" as values. This tag is similar to the 
FlowDirection property, but the FlowDirection property works in a more advanced way to layout textual content 
and can be used for content other than text. 

In WPF, a FlowDocument is a versatile Ul element that can host a combination of text, tables, images and other 
elements. The samples in the following sections use this element 

Adding text to a FlowDocument can be done in more that one way. A simple way to do so is through a Paragraph 
which is a block-level element used to group content such as text To add text to inline-level elements the samples 
use Span and Run. Span is an inline-level flow content element used for grouping other inline elements, while a 
Run is an inline-level flow content element intended to contain a run of unformatted text. A Span can contain 
multiple Run elements. 

The first document example contains a document that has a number of network share names; for example 
WserveniNfoidenXfiie.ext . Whether you have this network link in an Arabic or English document, you always want 
it to appear in the same way. The following graphic illustrates using the Span element and shows the link in an 
Arabic RightToLeft document: 
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<Page 

xmlns=”hcrp://schemas.micrcsoft.com/winfx/2006/xaml/presentation" 
xmlns:x=”http://schemas.microscft.ccm/winfx/2006/xaml” 
FlowDirection=”RightToLeft"s 
<FlcwDocuments 
<Paragraphs 

<Span FlowBirecticn="RightToLeft" s 
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</Spans 
</Paragraphs 
</FlowEocuments 
</Pages 

> 






Done. Markup saved to 'CAProgram Files\XamlPad\XamlPad_Savedxaml". 



Because the text is RightToLeft, all special characters, such as the separate the text in a right to left order. That 
results in the link not being shown in the correct order, therefore to solve the problem, the text must be embedded 
to preserve a separate Run flowing LeftToRight. Instead of having a separate Run for each language, a better way to 
solve the problem is to embed the less frequently used English text into a larger Arabic Span. 

The following graphic illustrates this by using the Run element embedded in a Span element: 
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1 of 1 


<Pa3e 

xmlns=”;i”':p: / / schemas .micrcsoft. com/winfx/2006/xaml/presencation” 
xmlns:x="http://schemas.microscft.ccm/winfx/200€/xaml" 
FlowDirec'i:ion="Righ'cToLefr"> 

<FlcwDocumen'c> 

<Para 3 raph> 

<Span FlowDirecT;ion="RighcTcLefc" > 


<Ruii FlowCirect±on="Lef'cTcRight”>\\serverl\filename\filenamel.txc</Run> 

uoj—ll p-J*. 

</Spans 
</Paragraph> 

</FlowDocument> 

</Pages 


Done. Markup saved to "CAProgram Files\XamlPad\XamlPad_Savedxaml”. 


The following example demonstrates using Run and Span elements in documents. 





































<Page 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http: //schemas. microsoft. com/winfx/2006/xaml" 
FlowDirection="RightToLeft"> 

<FlowDocument> 

<Paragraph> 

<Span FlowDirection="RightToLeft" > 

Ufl) volnJI \'>'i «i;: 

<Run FlowDirection="LeftToRight"> 

\\serverl\filename\filenamel.txt</Run> 

lyajJ I i_SvSlj fiJ ! 

</Span> 

</Paragraph> 

</FlowDocument> 

</Page> 


Span Elements 

The Span element works as a boundary separator between texts with different flow directions. Even Span elements 
with the same flow direction are considered to have different bidirectional scopes which means that the Span 
elements are ordered in the container's FlowDirection, only the content within the Span element follows the 
FlowDirection of the Span. 

The following graphic shows the flow direction of several TextBlock elements. 



The following example shows how to use the Span and Run elements to produce the results shown in the previous 
graphic. 
















<Page xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation"> 
cStackPanel > 

cTextBlock FontSize="20" FlowDir'ection="RightToLeft"> 

<Run FlowDirection="LeftToRight">/>Jl 2 jl</Run> 

<Run FlowDirection="LeftToRight" Foreground="Red" Ljv9</Run> 

</TextBlock> 

<TextBlock FontSize="20" FlowDir'ection="LeftToRight"> 

<Run FlowDirection="RightToLeft">/>JLsjJI</Run> 

<Run FlowDir'ectlon="RightToLeft" For'eground="Red" ,_sv3</Run> 

</TextBlock> 

<TextBlock FontSize="20" For'eground="Blue">/j\Luj /Jlsdk/TextBlockx 
cSepanaton/x 

<TextBlock FontSize="20" FlowDir'ection="RightToLeft"> 

<Span Foreground="Red" FlowDir'ection="LeftToRight">Flello</Span> 
<Span FlowDirection="LeftToRight">World</Span> 

</TextBlock> 

<TextBlock FontSize="20" FlowDir'ection="LeftToRight"> 

<Span Foregr'ound="Red" FlowDir'ection="RightToLeft">Flello</Span> 
<Span FlowDirection="RightToLeft">World</Span> 

</TextBlock> 

<TextBlock FontSize="20" For'eground="Blue">Flello World</TextBlock> 
</StackPanel> 

</Page> 


In the TextBlock elements in the sample, the Span elements are laid out according to the FlowDirection of their 
parents, but the text within each Span element flows according to its own FlowDirection. This is applicable to Latin 
and Arabic - or any other language. 

Adding xmhiang 

The following graphic shows another example that uses numbers and arithmetic expressions, such as 
"200.0+21.4=221.4" . Notice that only the FlowDirection is set. 
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<Page 

xmlns="!i':zp://3chenia3.inicrc3oft .com/winfx/2006/xaial/pre3e:i':ation" 
X3nln3:x="http: / /schemas .microscft. com/winfx/200€/xaml" 
FlowDirection="RighrTcLeft"> 

<FlowDocumenc> 

<Para 3 raph> 

<Span FlowDireccion="RighcToLefc"> 

221.4=200.0+21.4" h " 

</Span> 

</Paragraph> 

< / FlowDoc'jmeno 
</Page> 


Done. Markup saved to "CAProgram Files\XamlPad\XamlPad Saved.xaml". 


Users of this application will be disappointed by the output, even though the FlowDirection is correct the numbers 


























are not shaped as Arabic numbers should be shaped. 


XAML elements can include an XML attribute ( xmi:iang ) that defines the language of each element. XAML also 
supports a XML language principle whereby xmiriang values applied to parent elements in the tree are used by 
child elements. In the previous example, because a language was not defined for the Run element or any of its top 
level elements, the default xmi:iang was used, which is en-us for XAML. The internal number shaping algorithm 
of Windows Presentation Foundation (WPF) selects numbers in the corresponding language - in this case English. 
To make the Arabic numbers render correctly xmiriang needs to be set. 


The following graphic shows the example with xmi:iang added. 



The following example adds xmi:iang to the application. 

<Page 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

FlowDinection="RightToLeft"> 

<FlowDocument> 

<Paragnaph> 

<Span FlowDirection="RightToLeft" Language="ar-SA"> 

221.4=21.4+200.0" M^l" 

</Span> 

</Panagraph> 

</FlowDocument> 

</Page> 

Be aware that many languages have different xmi:iang values depending on the targeted region, for example, 


"ar-SA" 

and 

"ar- 

EG" 

represent two variations of Arabic. The previous examples illustrate that you need to define 

both the 

xml: 

lang 

and FlowDirection values. 


FlowDirection with Non-text Elements 

FlowDirection defines not only how text flows in a textual element but also the flow direction of almost every other 
Ul element. The following graphic shows a ToolBar that uses a horizontal LinearGradientBrush to draw its 
background with a left to right gradient. 



































After setting the FlowDirection to RightToLeft, not only the ToolBar buttons are arranged from right to left, but even 
the LinearGradientBrush realigns its offsets to flow from right to left. 

The following graphic shows the realignment of the LinearGradientBrush. 
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<Page 

xmln3="htcp://schemae.microsof^.com/winfx/2006/xaml/presentation" 
xmlna:x="http://schemas.micro3Oft.eom/winfx/2006/xaml" > 


> 

<Tocl5ar FlowDireotion="RighttoLeftj"> 

<ToolBar.5ackground> 





The following example draws a RightToLeftToolBar. (To draw it left to right, remove the FlowDirection attribute on 
the ToolBar. 












































<Page 

xtiilns="http: //schemas. micnosoft. com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml"> 

<ToolBar FlowDirection="RightToLeft" Height="50" DockPanel.Dock="Top"> 
<ToolBan.Background> 

cLinearGradientBrush StartPoint="0,0.5" EndPoint="lj1"> 
<LinearGradientBrush.GradlentStops> 

<GradientStop Color="DarkRed" Offset="0" /> 

<GradientStop Color="DarkBlue" Offset="0.3" /> 

<GradientStop Color="LightBlue" Offset="0.6" /> 

<GradientStop Color="White" Offset="l" /> 

</LineanGradientBrush.GnadientStops> 

</LinearGnadientBnush> 

</ToolBar.Background> 

<Button FontSize="12" Foreground="White">Buttonl</Button> 

<Rectangle Width="20"/> 

<Button FontSize="12" Foreground="White">Button2</Button> 

<Rectangle Width="20"/> 

<Button FontSize="12" Foreground="White">Button3</Button> 

<Rectangle Width="20"/> 

<Button FontSize="12" Foreground="White">Button4</Button> 

<Rectangle Width="20"/> 

</ToolBar> 

</Page> 


FlowDirection Exceptions 

There are a few cases where FlowDirection does not behave as expected. This section covers two of these 
exceptions. 

Image 

An Image represents a control that displays an image. In XAML it can be used with a Source property that defines 
the uniform resource identifier (URI) of the Image to display. 

Unlike other Ul elements, an Image does not inherit the FlowDirection from the container. However, if the 
FlowDirection is set explicitly to RightToLeft, an Image is displayed flipped horizontally. This is implemented as a 
convenient feature for developers of bidirectional content; because in some cases, horizontally flipping the image 
produces the desired effect. 


The following graphic shows a flipped Image. 
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<S'cackPansl < 

xmln3='ht:tp;//achemas.microsof*.com/winfx/2006/xaml/presenta-ion' rlowDirecoion="RighoToLefo"> 
<Image Souroe=’'file://c:/ni3_logo. jpg" Widih="147" Heigti'i="50"/> 

<Separator /> 

<Image Souroe="file://c:/ms_logo.jpg" Kidoh="147" Keig;i'i="50" FlowCirect;ion=”lefoToRight" /> 
<Separator /> 

<Iniage Souroe="file://c:/i!i3_logo.jpg” Widih="147" Keig!i':="50" FlowDireo'Dion=”RighoToLeft"/> 
</SracicPanel> , 


Done. Markup saved to 'CAProgram Files\XamlPad\XamlPad_Saved.xamr. 





























The following example demonstrates that the Image fails to inherit the FlowDirection from the StackPanel that 
contains it. 



<StackPanel 

xmlns='http://schemas.micnosoft.com/winfx/2006/xaml/presentation' 
FlowDirection="RightToLeft"> 


<Image Source="flie://c:/ms_logo.jpg" 

Width="147" Height="50"/> 
cSepanaton Height="10"/> 

<Image Source="flie://c:/ms_logo.jpg" 

Width="147" Height="50" FlowDir'ection="LeftToRight" /> 
cSepanaton Height="10"/> 

<Image Source="file://c:/ms_logo.jpg" 

Width="147" Height="50" FlowDir'ection="RightToLeft"/> 
</StackPanel> 


NOTE 

Included in the download files is an ms_logo.jpg file. The code assumes that the .jpg file is not inside your project but 
somewhere on the C:\ drive. You must copy the Jpg from the project files to your C:\ drive or change the code to look for the 
file inside the project. To do this change Source="fiIe://c:/ms_logo. jpg" to Source="ms_Iogo.jpg" . 


Paths 

In addition to an Image, another interesting element is Path. A Path is an object that can draw a series of connected 
lines and curves. It behaves in a manner similar to an Image regarding its FlowDirection; for example its 
RightToLeftFlowDirection is a horizontal mirror of its LeftToRight one. However, unlike an Image, Path inherits its 
FlowDirection from the container and one does not need to specify it explicitly. 

The following example draws a simple arrow using 3 lines. The first arrow inherits the RightToLeft flow direction 
from the StackPanel so that its start and end points are measured from a root on the right side. The second arrow 
which has an explicit RightToLeftFlowDirection also starts on the right side. However, the third arrow has its 
starting root on the left side. For more information on drawing see LineGeometry and GeometryGroup. 





<StackPanel 

xmlns='http://schemas.micnosoft.com/winfx/2006/xaml/presentation' 
FlowDirection="RightToLeft"> 

<Path Stroke="Blue" StrokeThickness="4"> 

<Path.Data> 

cGeometnyGroup > 

cLineGeometny Star'tPolnt="300j 10" EndPoint="350j30" /> 
cLineGeometny StartPoint="10j30" EndPoint="352j30" /> 
cLineGeometny StartPoint="300,50" EndPoint="350j30" /> 
c/GeometryGnoupx 
</Path.Data> 

</Path> 

<Path Stroke="Red" Str'okeThlckness="4" FlowDirection="RightToLeft"> 
<Path.Data> 

<GeometryGroup > 

cLineGeometny StartPoint="300,10" EndPoint="350j30" /> 
cLineGeometny StartPoint="10j30" EndPoint="352j30" /> 
cLineGeometny Star'tPoint="300j50" EndPoint="350j30" /> 
c/GeometryGnoupx 
</Path.Data> 

</Path> 

<Path Stroke="Gr'een" Str'okeThickness="4" FlowDirection="LeftToRight"> 
<Path.Data> 

<GeometryGroup > 

cLineGeometny Star'tPoint="300j 10" EndPoint="350j30" /> 
cLineGeometny Star'tPoint="10^30" EndPoint="352j30" /> 
cLineGeometny StartPoint="300j50" EndPoint="350j30" /> 
</GeometryGroup> 

</Path.Data> 

</Path> 

</StackPanel> 



The Image and Path are two examples of a how Windows Presentation Foundation (WPF) uses FlowDirection. 
Beside laying out Ul elements in a specific direction within a container, FlowDirection can be used with elements 
such as InkPresenter which renders ink on a surface, LinearGradientBrush, RadialGradientBrush. Whenever you 
need a right to left behavior for your content that mimics a left to right behavior, or vice versa, Windows 
Presentation Foundation (WPF) provides that capability. 


Number Substitution 

Historically, Windows has supported number substitution by allowing the representation of different cultural 
shapes for the same digits while keeping the internal storage of these digits unified among different locales, for 
example numbers are stored in their well known hexadecimal values, 0x40, 0x41, but displayed according to the 
selected language. 
















This has allowed applications to process numerical values without the need to convert them from one language to 
another, for example a user can open an Microsoft Excel spreadsheet in a localized Arabic Windows and see the 
numbers shaped in Arabic, but open it in a European version of Windows and see European representation of the 
same numbers. This is also necessary for other symbols such as comma separators and percentage symbol 
because they usually accompany numbers in the same document. 

Windows Presentation Foundation (WPF) continues the same tradition, and adds further support for this feature 
that allows more user control over when and how substitution is used. While this feature is designed for any 
language, it is particularly useful in bidirectional content where shaping digits for a specific language is usually a 
challenge for application developers because of the various cultures an application might run on. 

The core property controlling how number substitution works in Windows Presentation Foundation (WPF) is the 
Substitution dependency property. The NumberSubstitution class specifies how numbers in text are to be 
displayed. It has three public properties that define its behavior. The following is a summary of each of the 
properties: 

CultureSource: 

This property specifies how the culture for numbers is determined. It takes one of three NumberCultureSource 
enumeration values. 

• Override: Number culture is that of CultureOverride property. 

• Text: Number culture is the culture of the text run. In markup, this would be xml: lang , or its alias Language 
property (Language or Language). Also, it is the default for classes deriving from 
FrameworkContentElement. Such classes include System.Windows.Documents.Paragraph, 
System.Windows.Documents.Table, System.Windows.Documents.TableCell and so forth. 

• User: Number culture is the culture of the current thread. This property is the default for all subclasses of 
FrameworkElement such as Page, Window and TextBlock. 

CultureOverride: 

The CultureOverride property is used only if the CultureSource property is set to Override and is ignored 
otherwise. It specifies the number culture. A value of null , the default value, is interpreted as en-US. 

Substitution: 

This property specifies the type of number substitution to perform. It takes one of the following 
NumberSubstitutionMethod enumeration values: 

• AsCulture: The substitution method is determined based on the number culture's 
NumberFormatInfo.DigitSubstitution property. This is the default. 

• Context: If the number culture is an Arabic or Persian culture, it specifies that the digits depend on the 
context. 

• European: Numbers are always rendered as European digits. 

• NativeNational: Numbers are rendered using the national digits for the number culture, as specified by the 
culture's NumberFormat. 

• Traditional: Numbers are rendered using the traditional digits for the number culture. For most cultures, this 
is the same as NativeNational. However, NativeNational results in Latin digits for some Arabic cultures, 
whereas this value results in Arabic digits for all Arabic cultures. 

What do those values mean for a bidirectional content developer? In most cases, the developer might need only to 
define FlowDirection and the language of each textual Ul element, for example Language="an-SA" and the 
NumberSubstitution logic takes care of displaying the numbers according to the correct UL The following example 





demonstrates using Arabic and English numbers in a Windows Presentation Foundation (WPF) application running 
in an Arabic version of Windows. 


<Page 

xmlns="http: //schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" > 
cStackPaneIx 

<TextBlock Backgr'ound="LightGreen" FontSize="32" 

Language="ar'-SA" FlowDir'ection="RightToLeft">l+2=3</TextBlocks 
<TextBox Background="LightGreen" FontSize="32" 

Language="ar-SA" FlowDirection="RightToLeft">l+2=3</TextBox> 
<TextBlock Backgr'ound="LightBlue" FontSize="32">l+2=3</TextBlocks 
<TextBox Backgr'ound="LightBlue" FontSize="32"sl+2=3</TextBoxs 
</StackPanels 
</Pages 


The following graphic shows the output of the previous sample if you're running in an Arabic version of Windows 
with Arabic and English numbers displayed: 
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T=T+1 

r=T+i 


1+2 = 3 
1+2 = 3 

<Page 

xmln3="http: //schemas, microsoft. com/vfinfx/2906/xaml/presentation" 
xmlns : x="http://schemas.microsoft.com/winfx/2006/xaml" > 

<Staclcranel> 

<TextEloc)c 3ac}cground="LightGreen" FontSize="32" 

Language="ar-SA" FlowDirection="SightToLeft">l+2=3</TextBlooic> 

<TextBcx Background="LightGreen" FontSi2e="32" 

Language="ar-SA" FlowDirectior.="RightToLeft">l+2=3</TextBox> 

<IextBlock Bacjcground="LightBlue" FontSize="32">l+2=3</TextBlock> 
klextBcx Background="LightBlue” FontSize="32">l+2=3</Text3ox> 

</Stackranel> 

</Pages 


^ Done. Markup saved to 'C:\Program Files\XamlPad\XamlPad_Savedjcamr. 


The FlowDirection was important in this case because setting the FlowDirection to LeftToRight instead would have 
yielded European digits. The following sections discuss how to have a unified display of digits throughout your 
document. If this example is not running on Arabic Windows, all the digits display as European digits. 

Defining Substitution Rules 

In a real application you might need to set the Language programmatically. For example, you want to set the 
xmi:iang attribute to be the same as the one used by the system's Ul, or maybe change the language depending 
on the application state. 

If you want to make changes based on the application's state, make use of other features provided by Windows 
Presentation Foundation (WPF). 
















First, set the application component's Number'Substitution.cuitureSource="Text" . Using this setting makes sure that 
the settings do not come from the Ul for text elements that have "User" as the default, such as TextBlock. 

For example: 

<TextBlocl< 

IMame="textl" NumberSubstitution.CultureSource="Text"> 

1234+5679=6913 

</TextBlock> 

In the corresponding C# code, set the Language property, for example, to "ar-SA" . 

textl.Language = System.Windows.Markup.XmlLanguage.GetLanguage("ar-SA"); 

If you need to set the Language property to the current user's Ul language use the following code. 

textl.Language = 

System.Windows.Markup.XmlLanguage.GetLanguage(System.Globalization.CultureInfo.CurrentUICulture.IetfLanguageTa 
g); 


CultureInfo.CurrentCulture represents the current culture used by the current thread at run time. 
Your final XAML example should be similar to the following example. 

<Page x:Class="WindowsApplication.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http: //schemas. microsoft. com/winfx/2006/xaml" 

Title="Code Sample" Height="300" Width="300" 

> 

<StackPanel> 

<TextBlock Language="ar-SA" 

FlowDirection="RightToLeft" >3=2+1 : 

</TextBlock> 

cTextBlock Language="ar-SA" 

FlowDirection="RlghtToLeft" 

NumberSubstitution.Substitution="European">3=2+1 
</TextBlock> 

</StackPanel> 

</Page> 


Your final C# example should be similar to the following. 









namespace BidiTest 

{ 

public partial class Windowl : Window 

{ 

public WindowlO 

{ 

InitializeComponent(); 
string currentLanguage = 

System.Globalization.CultureInfo.CurrentCulture.IetfLanguageTag; 

textl.Language = System.Windows.Markup.XmlLanguage.GetLanguage(currentLanguage); 

if (currentLanguage.ToLower().StartsWith("ar")) 

{ 

textl.FlowDirection = FlowDirection.RightToLeft; 

} 

else 

{ 

textl.FlowDirection = FlowDirection.LeftToRight; 

} 

} 

} 

} 

The following graphic shows what the window looks like for either programming language, displaying Arabic 
numbers: 
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Using the Substitution Property 

The way number substitution works in Windows Presentation Foundation (WPF) depends on both the Language of 
the text element and its FlowDirection. If the FlowDirection is left to right, then European digits are rendered. 
Flowever if it is preceded by Arabic text, or has the language set to "ar" and the FlowDirection is RightToLeft, Arabic 
digits are rendered instead. 

In some cases, however, you might want to create a unified application, for example European digits for all users. 

Or Arabic digits in Table cells with a specific Style. One easy way to do that is using the Substitution property. 

In the following example, the first TextBlock does not have the Substitution property set, so the algorithm displays 
Arabic digits as expected. However in the second TextBlock, the substitution is set to European overriding the 
default substitution for Arabic numbers, and European digits are displayed. 

<Page x:Class="WindowsApplication.Windowl" 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

Title="Code Sample" Height="300" Width="300" 

> 

<StackPanel> 

<TextBlock Language="ar-SA" 

FlowDinection="RightToLeft">3=2+1 : 

</TextBlock> 

<TextBlock Language="ar-SA" 

FlowDinection="RightToLeft" 

NumberSubstitution.Substitution="European">3=2+1 
</TextBlock> 

</StackPanel> 

</Page> 











Howto: Localize an application 

5/12/2020 • 6 minutes to read ^ Edit Online 


This tutorial explains how to create a localized application by using the LocBamI tool. 


NOTE 

The LocBamI tool is not a production-ready application. It is presented as a sample that uses some of the localization APIs 
and illustrates how you might write a localization tool. 


Overview 

This article gives you a step-by-step approach to localizing an application. First, you prepare your application so 
that the text that will be translated can be extracted. After the text is translated, you merge the translated text into 
a new copy of the original application. 

Create a sample application 

In this step, you prepare your app for localization. In the Windows Presentation Foundation (WPF) samples, a 
HelloApp sample is supplied that will be used for the code examples in this discussion. If you would like to use 
this sample, download the Extensible Application Markup Language (XAML) files from the LocBamI Tool Sample. 

1. Develop your application to the point where you want to start localization. 

2. Specify the development language in the project file so that MSBuild generates a main assembly and a 
satellite assembly (a file with the .resources.dll extension) to contain the neutral language resources. The 
project file in the HelloApp sample is HelloApp.csproj. In that file, you will find the development language 
identified as follows: 


<LIICultur'e>en-US</UICulture> 


3. Add Uids to your XAML files. Uids are used to keep track of changes to files and to identify items that must 
be translated. To add Uids to your files, run updateuid on your project file: 

msbuild -t:updateuid helloapp.csproj 

To verify that you have no missing or duplicate Uids, run checkuid : 
msbuild -t:checkuid helloapp.csproj 

After running updateuid , your files should contain Uids. For example, in the Panel.xamliWe of HelloApp, 
you should find the following: 

<StackPanel x:Uid="StackPanel_l"> 

<TextBlock x:Uid="TextBlock_l">Hello Wonld</TextBlock> 

<TextBlock x:Llid="TextBlock_2">Goodbye World</TextBlock> 

</StackPanel> 


Create the neutral-language resources satellite assembly 

After the application is configured to generate a neutral-language resources satellite assembly, you build the 
application. This generates the main application assembly as well as the neutral-language resources satellite 











assembly that's required by LocBamI for localization. 


To build the application: 

1. Compile HelloApp to create a dynamic-link library (DLL): 

msbuild helloapp.cspnoj 

2. The newly created main application assembly, HelloApp.exe, is created in the following folder: 

C:\HelloApp 1 Bin 1 Debug 

3. The newly created neutral-language resources satellite assembly, HelloApp.resources.dll, is created in the 
following folder: C:\HelloApp\Bin\Debug\en-US 

Build the LocBamI tool 

1. All the files necessary to build LocBamI are located in the WPF samples. Download the C# files from the 
LocBamI Tool Sample. 

2. From the command line, run the project file (locbaml.csproj) to build the tool: 
msbuild locbaml.csproj 

3. Go to the Bln\Release directory to find the newly created executable file (locbaml.exe). Example: 

C:\L ocBaml\Bin 1 Release\locbaml. exe 

4. The options that you can specify when you run LocBamI are as follows. 


OPTION DESCRIPTION 


parse or -p 

Parses BamI, resources, or DLL files to generate a .csv or 
.txt file. 

generate or -g 

Generates a localized binary file by using a translated file. 

out or -0 {filedirector^ 

Output file name. 

culture or -cul {culture] 

Locale of output assemblies. 

translation or -trans [translation.csv] 

Translated or localized file. 

asmpath or -asmpath [filedirectory] 

If your XAML code contains custom controls, you must 
supply the asmpath to the custom control assembly. 

nologo 

Displays no logo or copyright information. 

verbose 

Displays verbose mode information. 


NOTE 

If you need a list of the options when you are running the tool, enter LocBaml.exe and then press Enter. 


Use LocBamI to parse a file 

Now that you have created the LocBamI tool, you are ready to use it to parse HelloApp.resources.dll to extract the 
text content that will be localized. 




















1. Copy LocBaml.exe to your application's bin\debug folder, where the main application assembly was 
created. 

2. To parse the satellite assembly file and store the output as a .csv file, use the following command: 



3. When you run LocBamI to parse files, the output consists of seven fields delimited by commas (.csv files) or 
tabs (.txt files). The following shows the parsed .csv file for the HelloApp.resources.dll: 


HelloApp.g.en-US.resources:window1.baml,Stad<1:System.Windows.Controls.Stad<Panel.$Content, Ignore,FALSE, 
FALSE„#Text1;#Text2; 

HelloApp.g.en-US.resources:window1.baml,Text1:System.Windows.Controls.TextBlod<.$Content,None,TRUE, TRUE„Hello 
World 

HelloApp.g.en-US.resources:window1.baml,Text2:System.Windows.Controls.TextBlod<.$Content,None,TRU E, 
TRUE„Goodbye World 

The seven fields are: 

• BAML Name. The name of the BAML resource with respect to the source language satellite 
assembly. 

• Resource Key. The localized resource identifier. 

• Category. The value type. See Localization Attributes and Comments. 

• Readability. Whether the value can be read by a localizer. See Localization Attributes and 
Comments. 

• Modifiability. Whether the value can be modified by a localizer. See Localization Attributes and 
Comments. 

• Comments. Additional description of the value to help determine how a value is localized. See 
Localization Attributes and Comments. 

• Value. The text value to translate to the desired culture. 

The following table shows how these fields map to the delimited values of the .csv file: 


BAML NAME 

RESOURCE 

KEY 

CATEGORY 

READABILITY 

MODIFIABILI 

TY 

COMMENTS 

VALUE 

HelloApp.g.e 

n- 

US.resources: 

windowl.ba 

ml 

Stack 1 :Syste 
m.Windows. 

Controls.Stac 

kPanel.$Cont 

ent 

Ignore 

FALSE 

FALSE 


#Text1;#Text2 




BAML NAME 

RESOURCE 

KEY 

CATEGORY 

READABILITY 

MODIFIABILI 

TY 

COMMENTS 

VALUE 

HelloApp.g.e 

n- 

US.resources: 

windowl.ba 

ml 

Textl :System. 
Windows.Co 

ntrols.TextBlo 

ck.$Content 

None 

TRUE 

TRUE 


Hello World 


HelloApp.g.e 

n- 

US.resources: 

windowl.ba 

ml 


Text2:System. 

Windows.Co 

ntrols.TextBlo 

ck.$Content 


None 


TRUE 


TRUE 


Goodbye 

World 


Notice that all the values for the Comments field contain no values; if a field doesn't have a value, it is 
empty. Also notice that the item in the first row is neither readable nor modifiable, and has "Ignore" as its 
Category value, all of which indicates that the value is not localizable. 

4. To facilitate discovery of localizable items in parsed files, particularly in large files, you can sort or filter the 
items by Category, Readability, and Modifiability. For example, you can filter out unreadable and 
unmodifiable values. 


Translate the localizable content 

Use any tool that you have available to translate the extracted content. A good way to do this is to write the 
resources to a .csv file and view them in Microsoft Excel, making translation changes to the last column (value). 

Use LocBamI to generate a new .resources.dll file 

The content that was identified by parsing HelloApp.resources.dll with LocBamI has been translated and must be 
merged back into the original application. Use the generate or -g option to generate a new .resources.dll file. 

1. Use the following syntax to generate a new HelloApp.resources.dll file. Mark the culture as en-US (/cul:en- 


US). 

LocBaml.exe /generate HelloApp.resources.dll /trans:Hello.csv /out:c:\ /cul:en-US 



2. Replace the old HelloApp.resources.dllY\\e in the C:\HelloApp\Bln\Debug\en-US\HelloApp.resources.dll 
directory with your newly created HelloApp.resources.dll f\\e. 

3. "Hello World" and "Goodbye World" should now be translated in your application. 

4. To translate to a different culture, use the culture of the language that you are translating to. The following 
example shows how to translate to French-Canadian: 

LocBaml.exe /generate HelloApp.resources.dll /trans:Hellofr-CA.csv /out:c:\ /cul:fr-CA 

5. In the same assembly as the main application assembly, create a new culture-specific folder to house the 
new satellite assembly. For French-Canadian, the folder would be fr-CA. 

6. Copy the generated satellite assembly to the new folder. 







7. To test the new satellite assembly, you need to change the culture under which your application will run. 
You can do this in one of two ways: 

• Change your operating system's regional settings. 

• In your application, add the following code to App.xaml.es: 

<Application 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

X:Class="SDKSample.App" 
x:Uid="Application_l" 

StartupUri="Windowl.xaml"> 

</Application> 


using System.Windows; 
using System.Globalization; 
using System.Threading; 

namespace SDKSample 

{ 

public partial class App : Application 

{ 

public AppO 

{ 

// Change culture under which this application runs 
Cultureinfo ci = new CultureInfo("fr-CA"); 

Thread.CurrentThread.CurrentCulture = ci; 

Thread.CurrentThread.CurrentUICulture = ci; 

} 

} 

} 


Imports System.Windows 
Imports System.Globalization 
Imports System.Threading 

Namespace SDKSample 

Partial Public Class App 
Inherits Application 
Public Sub New() 

' Change culture under which this application runs 
Dim ci As New CultureInfo("fr-CA") 

Thread.CurrentThread.CurrentCulture = ci 
Thread.CurrentThread.CurrentUICulture = ci 
End Sub 
End Class 
End Namespace 


Tips for Using LocBamI 

• All dependent assemblies that define custom controls must be copied into the local directory of LocBamI 
or installed into the GAC. This is necessary because the localization API must have access to the dependent 
assemblies when it reads the binary XAML (BAML). 

• If the main assembly is signed, the generated resource DLL must also be signed in order for it to be loaded. 


• The version of the localized resource DLL needs to be synchronized with the main assembly. 



See also 


• Globalization for WPF 

• Use Automatic Layout Overview 


How to; Use Automatic Layout to Create a Button 

3/25/2019 • 2 minutes to read ^ Edit Online 


This example describes how to use the automatic layout approach to create a button in a localizable application. 

Localization of a user interface (Ul) can be a time consuming process. Often localizers need to resize and reposition 
elements in addition to translating text. In the past each language that a Ul was adapted for required adjustment. 
Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that reduce the 
need for adjustment. The approach to writing applications that can be more easily resized and repositioned is 
called automatic layout . 

Example 

The following two Extensible Application Markup Language (XAML) examples create applications that instantiate a 
button; one with English text and one with Spanish text. Notice that the code is the same except for the text; the 
button adjusts to fit the text. 

<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="ButtonLoc.Panel" 

Name="myWindow" 

SizeToContent="WidthAndHeight" 

> 

cDockPaneIx 

<Button FontSize="28" Height="50">My name is Hope.</Button> 

</DockPanel> 

</Window> 


<Window 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="ButtonLoc.Panel" 

Name="myWindow" 

SizeToContent="WidthAndHeight" 

> 

<DockPanel> 

<Button FontSize="28" Height="50">Me llamo Esperanza.</Button> 
</DockPanel> 

</Window> 

















See also 

• Use Automatic Layout Overview 

• Use a Grid for Automatic Layout 


How to: Use a Grid for Automatic Layout 

4/8/2019 • 2 minutes to read ^ Edit Online 


This example describes how to use a grid in the automatic layout approach to creating a localizable application. 

Localization of a user interface (Ul) can be a time consuming process. Often localizers need to re-size and 
reposition elements in addition to translating text. In the past each language that a Ul was adapted for required 
adjustment. Now with the capabilities of Windows Presentation Foundation (WPF) you can design elements that 
reduce the need for adjustment. The approach to writing applications that can be more easily re-sized and 
repositioned is called auto layout . 

The following Extensible Application Markup Language (XAML) example demonstrates using a grid to position 
some buttons and text. Notice that the height and width of the cells are set to Auto ; therefore the cell that contains 
the button with an image adjusts to fit the image. Because the Grid element can adjust to its content it can be 
useful when taking the automatic layout approach to designing applications that can be localized. 

Example 

The following example shows how to use a grid. 






<Grid Name="grid" ShowGnidLines ="false"> 
<Grid.ColumnDefinitions> 

<ColumnDefinition Width="Auto"/> 
<ColumnDefinition Width="*"/> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinltion Height="Auto"/> 
<RowDefinltion Height="Auto"/> 
<RowDefinition Height="Auto"/> 
<RowDefinition Height="Auto"/> 
<RowDefinltion Height="Auto"/> 

</Gnid.RowDefinitlons> 


<TextBlocl< Margin="10j 10j 5^ 5" Grid.Column="0" Grid.Row="0" FontSize="24">Grid 
</TextBlock> 

<TextBlocl< Margin="10j 10j S, 5" Grid.Column="0" Grid.Row="l" FontSize="12" 

Grid.ColumnSpan="2">The following buttons and text are positioned using a Grid. 
</TextBlock> 

<Button Margin="10j 10, S, 5" Grid.Column="0" Grid.Row="2" Background="Pink" 
BorderBrush="Black" BorderThickness="10">Button 1 
</Button> 

5" Grid.Column="l" Grid.Row="2" FontSize="12" 
TextWrapping="WrapWithOverflow">Sets the background 


Grid.Column="0" Grid.Row="3" Foreground="Red"> 


cTextBlock Margin="10, 10, 5, 

VerticalAlignment="Center" 
color. 

</TextBlock> 

<Button Margin="10, 10, 5, 5" 

Button 2 

</Button> 

<TextBlock Margin="10, 10, 5, 5" Grid.Column="l" Grid.Row="3" FontSize="12" 

VerticalAlignment="Center" TextWrapping="WrapWithOverflow">Sets the foreground 
color. 

</TextBlock> 

<Button Margin="10, 10, 5, 5" Grid.Column="0" Grid.Row="4"> 

<Image Source="data\flower.jpg"></Image> 

</Button> 

<TextBlock Margin="10, 10, 5, 5" Grid.Column="l" Grid.Row="4" FontSize="12" 
VerticalAlignment="Center" TextWrapping="WrapWithOverflow">Adds an image as 
the button's content. 

</TextBlock> 

</Grid> 


The following graphic shows the output of the code sample. 



Grid 


See also 


• Use Automatic Layout Overview 

• Use Automatic Layout to Create a Button 












How to: Use a ResourceDictionary to Manage 
Localizable String Resources 

9 • 2 minutes to read i Edit Online 


This example shows how to use a ResourceDictionary to package localizable string resources for Windows 
Presentation Foundation (WPF) applications. 

To use a ResourceDictionary to manage localizable string resources 

1. Create a ResourceDictionary that contains the strings you would like to localize. The following code shows 
an example. 

<ResourceDictionary 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
xmlns:system="clr-namespace:System;assembly=mscorlib"> 

<!-- String resource that can be localized --> 

<system:String x:Key="localizedMessage">en-LIS Message</system:String> 

</ResourceDictionary> 

This code defines a string resource, locaiizedMessage , of type String, from the System namespace in 
mscorlib.dll. 

2. Add the ResourceDictionary to your application, using the following code. 

<Application.Resources> 

<ResourceDictionary> 

cResourceDictionary.MergedDictionaries> 

<ResourceDictionary Source="StringResources.xaml" /> 

</ResourceDictionary.MergedDictionaries> 

</ResourceDictionary> 

</Application.Resources> 


3. Use the string resource from markup, using Extensible Application Markup Language (XAML) like the 
following. 

<!-- Declarative use of string resource from StringResources.xaml resource dictionary --> 
<TextBox DockPanel.Dock="Top" Text="{StaticResource locaiizedMessage}" /> 


4. Use the string resource from code-behind, using code like the following. 

// Programmatic use of string resource from StringResources.xaml resource dictionary 
string locaiizedMessage = (string)Application.Current.FindResource("localizedMessage"); 
MessageBox.Show(localizedMessage); 


' Programmatic use of string resource from StringResources.xaml resource dictionary 

Dim locaiizedMessage As String = CStr(Application.Current.FindResource("localizedMessage")) 

MessageBox.Show(locaiizedMessage) 









5. Localize the application. For more information, see Localize an Application. 


How to; Use resources in localizable apps 

5/12/2020 • 2 minutes to read ^ Edit Online 


Localization means to adapt a user interface to different cultures. To do this, text such as titles, captions, and list box 
items must be translated. To make translation easier, the items to be translated are collected into resource files. See 
Localize an app for information on how to create a resource file for localization. To make a WPF application 
localizable, developers need to build all the localizable resources into a resource assembly. The resource assembly 
is localized into different languages, and the code-behind uses resource management API to load. 

Example 

One of the files required for a WPF application is a project file (.proj). All resources that you use in your application 
should be included in the project file. The following XAML example shows this. 

<Resource Include="data\picturel.jpg"/> 

<EmbeddedResource Include="data\stringtable.en-US.restext"/> 


To use a resource in your application, instantiate ResourceManager and load the resource you want to use. The 
following C# code demonstrates how to do this. 

void OnClicl<(object sender^ RoutedEventArgs e) 

{ 

ResourceManager rm = new ResourceManager ("MySampleApp.data.stringtable"j 
Assembly .GetExecutingAssemblyO); 

Textl.Text = rm.GetStringC'Message"); 

} 


See also 


• Localize an app 






Layout 

8/17/2020 • 9 minutes to read i Edit Online 


This topic describes the Windows Presentation Foundation (WPF) layout system. Understanding how and when 
layout calculations occur is essential for creating user interfaces in WPF. 

This topic contains the following sections: 

• Element Bounding Boxes 

• The Layout System 

• Measuring and Arranging Children 

• Panel Elements and Custom Layout Behaviors 

• Layout Performance Considerations 

• Sub-pixel Rendering and Layout Rounding 

• What's Next 

Element Bounding Boxes 

When thinking about layout in WPF, it is important to understand the bounding box that surrounds all elements. 
Each FrameworkElement consumed by the layout system can be thought of as a rectangle that is slotted into the 
layout. The Layoutinformation class returns the boundaries of an element's layout allocation, or slot. The size of 
the rectangle is determined by calculating the available screen space, the size of any constraints, layout-specific 
properties (such as margin and padding), and the individual behavior of the parent Panel element. Processing this 
data, the layout system is able to calculate the position of all the children of a particular Panel. It is important to 
remember that sizing characteristics defined on the parent element, such as a Border, affect its children. 

The following illustration shows a simple layout. 

Hello Worldl 

Show Bounding Box 


This layout can be achieved by using the following XAML. 






<Grid Name="myGr'id" Bacl<ground="LightSteelBlue" Height="150"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="250"/> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition /> 

<RowDefinition /> 

<RowDefinition /> 

</Grid.RowDefinitions> 

<TextBlock Name="txtl" Mangin="5" FontSize="16" FontFamily="Vendana" Gnid.Column="0" Gnid.Row="0">Flello 
World!</TextBlock> 

<Button Click="getLayoutSlotl" Width="125" Fleight="25" Grid.Column="0" Grid.Row="l">Show Bounding 
Box</Button> 

<TextBlock Name="txt2" Grid.Column="l" Grid.Row="2"/> 

</Grid> 


A single TextBlock element is hosted within a Grid. While the text fills only the upper-left corner of the first column, 
the allocated space for the TextBlock is actually much larger. The bounding box of any FrameworkElement can be 
retrieved by using the GetLayoutSlot method. The following illustration shows the bounding box for the TextBlock 
element. 


Hello Worldl 


Show Bounding Box 


LayoutSlot is equal to 0,0,250,50 


As shown by the yellow rectangle, the allocated space for the TextBlock element is actually much larger than it 
appears. As additional elements are added to the Grid, this allocation could shrink or expand, depending on the 
type and size of elements that are added. 

The layout slot of the TextBlock is translated into a Path by using the GetLayoutSlot method. This technique can be 
useful for displaying the bounding box of an element. 

private void getLayoutSlotl(object sender. System.Windows.RoutedEventArgs e) 

{ 

RectangleGeometry myRectangleGeometry = new RectangleGeometryO; 

myRectangleGeometry.Rect = Layoutinformation.GetLayoutSlot(txtl)j 

Path myPath = new Path(); 

myPath.Data = myRectangleGeometry; 

myPath.Stroke = Brushes.LightGoldenrodYellow; 

myPath.StrokeThickness = 5; 

Grid.SetColumn(myPath, 0); 

Grid.SetRow(myPath, 0); 
myGrid.Children.Add(myPath); 

txt2.Text = "LayoutSlot is equal to " + Layoutinformation.GetLayoutSlot(txtl) .ToStringO; 

} 








Private Sub getLayoutSlotl(ByVal sender As Object, ByVal e As RoutedEventArgs) 

Dim myRectangleGeometry As New RectangleGeometry 
myRectangleGeometry.Rect = Layoutinformation.GetLayoutSlot(txtl) 

Dim myPath As New Path 
myPath.Data = myRectangleGeometry 
myPath.Stroke = Brushes.LightGoldenrodYellow 
myPath.StrokeThickness = 5 
Grid.SetColumn(myPath, 0) 

Grid.SetRow(myPath, 0) 
myGrid.Children.Add(myPath) 

txt2.Text = "LayoutSlot is equal to " + Layoutinformation.GetLayoutSlot(txtl).ToStringO 
End Sub 


The Layout System 

At its simplest, layout is a recursive system that leads to an element being sized, positioned, and drawn. More 
specifically, layout describes the process of measuring and arranging the members of a Panel element's Children 
collection. Layout is an intensive process. The larger the Children collection, the greater the number of calculations 
that must be made. Complexity can also be introduced based on the layout behavior defined by the Panel element 
that owns the collection. A relatively simple Panel, such as Canvas, can have significantly better performance than 
a more complex Panel, such as Grid. 

Each time that a child UlElement changes its position, it has the potential to trigger a new pass by the layout 
system. Therefore, it is important to understand the events that can invoke the layout system, as unnecessary 
invocation can lead to poor application performance. The following describes the process that occurs when the 
layout system is invoked. 

1. A child UlElement begins the layout process by first having its core properties measured. 

2. Sizing properties defined on FrameworkElement are evaluated, such as Width, Height, and Margin. 

3. Panel-specific logic is applied, such as Dock direction or stacking Orientation. 

4. Content is arranged after all children have been measured. 

5. The Children collection is drawn on the screen. 

6. The process is invoked again if additional Children are added to the collection, a LayoutTransform is 
applied, or the UpdateLayout method is called. 

This process and how it is invoked are defined in more detail in the following sections. 

Measuring and Arranging Children 

The layout system completes two passes for each member of the Children collection, a measure pass and an 
arrange pass. Each child Panel provides its own MeasureOverride and ArrangeOverride methods to achieve its 
own specific layout behavior. 

During the measure pass, each member of the Children collection is evaluated. The process begins with a call to 
the Measure method. This method is called within the implementation of the parent Panel element, and does not 
have to be called explicitly for layout to occur. 

First, native size properties of the UlElement are evaluated, such as Clip and Visibility. This generates a value 
named constnaintsize that is passed to MeasureCore. 

Secondly, framework properties defined on FrameworkElement are processed, which affects the value of 
constraintsize . These properties generally describe the sizing characteristics of the underlying UlElement, such 
as its Height, Width, Margin, and Style. Each of these properties can change the space that is necessary to display 





the element. MeasureOverride is then called with constraintsize as a parameter. 


NOTE 

There is a difference between the properties of Height and Width and ActualHeight and ActualWidth. For example, the 
ActualHeight property is a calculated value based on other height inputs and the layout system. The value is set by the 
layout system itself based on an actual rendering pass, and may therefore lag slightly behind the set value of properties, 
such as Height, that are the basis of the input change. 

Because ActualHeight is a calculated value, you should be aware that there could be multiple or incremental reported 
changes to it as a result of various operations by the layout system. The layout system may be calculating required measure 
space for child elements, constraints by the parent element, and so on. 


The ultimate goal of the measure pass is for the child to determine its DesiredSize, which occurs during the 
MeasureCore call. The DesiredSize value is stored by Measure for use during the content arrange pass. 

The arrange pass begins with a call to the Arrange method. During the arrange pass, the parent Panel element 
generates a rectangle that represents the bounds of the child. This value is passed to the ArrangeCore method for 
processing. 

The ArrangeCore method evaluates the DesiredSize of the child and evaluates any additional margins that may 
affect the rendered size of the element. ArrangeCore generates an arnangesize , which is passed to the 
ArrangeOverride method of the Panel as a parameter. ArrangeOverride generates the finaisize of the child. 
Finally, the ArrangeCore method does a final evaluation of offset properties, such as margin and alignment, and 
puts the child within its layout slot. The child does not have to (and frequently does not) fill the entire allocated 
space. Control is then returned to the parent Panel and the layout process is complete. 

Panel Elements and Custom Layout Behaviors 

WPF includes a group of elements that derive from Panel. These Panel elements enable many complex layouts. For 
example, stacking elements can easily be achieved by using the StackPanel element, while more complex and free 
flowing layouts are possible by using a Canvas. 

The following table summarizes the available layout Panel elements. 


PANEL NAME 

DESCRIPTION 

Canvas 

Defines an area within which you can explicitly position child 
elements by coordinates relative to the Canvas area. 

DockPanel 

Defines an area within which you can arrange child elements 
either horizontally or vertically, relative to each other. 

Grid 

Defines a flexible grid area that consists of columns and rows. 

StackPanel 

Arranges child elements into a single line that can be oriented 
horizontally or vertically. 

VirtualizingPanel 

Provides a framework for Panel elements that virtualize their 

child data collection. This is an abstract class. 

WrapPanel 

Positions child elements in sequential position from left to 
right, breaking content to the next line at the edge of the 
containing box. Subsequent ordering occurs sequentially from 
top to bottom or right to left, depending on the value of the 
Orientation property. 





For applications that require a layout that is not possible by using any of the predefined Panel elements, custom 
layout behaviors can be achieved by inheriting from Panel and overriding the MeasureOverride and 
ArrangeOverride methods. 

Layout Performance Considerations 

Layout is a recursive process. Each child element in a Children collection gets processed during each invocation of 
the layout system. As a result, triggering the layout system should be avoided when it is not necessary. The 
following considerations can help you achieve better performance. 

• Be aware of which property value changes will force a recursive update by the layout system. 

Dependency properties whose values can cause the layout system to be initialized are marked with public 
flags. AffectsMeasure and AffectsArrange provide useful clues as to which property value changes will 
force a recursive update by the layout system. In general, any property that can affect the size of an 
element's bounding box should have a AffectsMeasure flag set to true. For more information, see 
Dependency Properties Overview. 

• When possible, use a RenderTransform instead of a LayoutTransform. 

A LayoutTransform can be a very useful way to affect the content of a user interface (Ul). However, if the 
effect of the transform does not have to impact the position of other elements, it is best to use a 
RenderTransform instead, because RenderTransform does not invoke the layout system. LayoutTransform 
applies its transformation and forces a recursive layout update to account for the new position of the 
affected element. 

• Avoid unnecessary calls to UpdateLayout. 

The UpdateLayout method forces a recursive layout update, and is frequently not necessary. Unless you are 
sure that a full update is required, rely on the layout system to call this method for you. 

• When working with a large Children collection, consider using a VirtualizingStackPanel instead of a regular 
StackPanel. 

By virtualizing the child collection, the VirtualizingStackPanel only keeps objects in memory that are 
currently within the parent's ViewPort. As a result, performance is substantially improved in most scenarios. 

Sub-pixel Rendering and Layout Rounding 

The WPF graphics system uses device-independent units to enable resolution and device independence. Each 
device independent pixel automatically scales with the system's dots per inch (dpi) setting. This provides WPF 
applications proper scaling for different dpi settings and makes the application automatically dpi-aware. 

However, this dpi independence can create irregular edge rendering because of anti-aliasing. These artifacts, 
typically seen as blurry or semi-transparent edges, can occur when the location of an edge falls in the middle of a 
device pixel instead of between device pixels. The layout system provides a way to adjust for this with layout 
rounding. Layout rounding is where the layout system rounds any non-integral pixel values during the layout 
pass. 

Layout rounding is disabled by default. To enable layout rounding, set the UseLayoutRounding property to true 
on any FrameworkElement. Because it is a dependency property, the value will propagate to all the children in the 
visual tree. To enable layout rounding for the entire Ul, set UseLayoutRounding to true on the root container. For 
an example, see UseLayoutRounding. 

What's Next 

Understanding how elements are measured and arranged is the first step in understanding layout. For more 




information about the available Panel elements, see Panels Overview. To better understand the various positioning 
properties that can affect layout, see Alignment, Margins, and Padding Overview. When you are ready to put it all 
together in a lightweight application, see Walkthrough: My first WPF desktop application. 

See also 

• FrameworkElement 

• UlElement 

• Panels Overview 

• Alignment, Margins, and Padding Overview 

• Layout and Design 


Migration and Interoperability 

3/25/2020 • 2 minutes to read • Edit Online 

This page contains links to documents that discuss how to implement interoperation between Windows 

Presentation Foundation (WPF) applications and other types of Microsoft Windows applications. 

In This Section 

Types migrated from WPF to System.XamI 

WPF and Windows Forms Interoperation 

WPF and Win32 Interoperation 

WPF and Direct3D9 Interoperation 


Reference 


TERM 

DEFINITION 

WindowsFormsFlost 

An element that you can use to host a Windows Forms 
control as an element of a WPF page. 

ElementHost 

A Windows Forms control that you can use to host a 

Windows Presentation Foundation (WPF) control. 

FlwndSource 

Flosts a WPF region within a Win32 application. 

Flwndhlost 

Base class for WindowsFormsFlost, defines some basic 
functionality that all FIWND-based technologies use when 
hosted by a WPF application. Subclass this to host a Win32 
window within a WPF application. 

BrowserInteropFlelper 

A helper class for reporting conditions of the browser 
environment for a WPF application that is hosted by a 
browser. 


Related Sections 




Types migrated from WPF to System.XamI 

3/25/2020 • 5 minutes to read ^ Edit Online 


In .NET Framework 3.5 and .NET Framework 3.0, both Windows Presentation Foundation (WPF) and Windows 
Workflow Foundation included a XAML language implementation. Many of the public types that provided 
extensibility for the WPF XAML implementation existed in the WindowsBase, PresentationCore, and 
PresentationFramework assemblies. Likewise, public types that provided extensibility for Windows Workflow 
Foundation XAML existed in the System.Workflow.ComponentModel assembly. In the .NET Framework 4, some of 
the XAML-related types were migrated to the System.XamI assembly. A common .NET Framework implementation 
of XAML language services enables many XAML extensibility scenarios that were originally defined by a specific 
framework's XAML implementation but are now part of overall .NET Framework 4 XAML language support. This 
article lists the types that were migrated and discusses issues related to the migration. 

Assemblies and Namespaces 

In .NET Framework 3.5 and .NET Framework 3.0, the types that WPF implemented to support XAML were generally 
in the System.Windows.Markup namespace. Most of these types were in the WindowsBase assembly. 

In .NET Framework 4, there is a new System.XamI namespace and a new System.XamI assembly. Many of the types 
that were originally implemented for WPF XAML are now provided as extensibility points or services for any 
implementation of XAML. As part of making them available for more general scenarios, the types are type- 
forwarded from their original WPF assembly to the System.XamI assembly. This enables XAML extensibility 
scenarios without having to include the assemblies of other frameworks (such as WPF and Windows Workflow 
Foundation). 

For migrated types, most of the types remain in the System.Windows.Markup namespace. This was partially to 
avoid breaking CLR namespace mappings in existing implementations on a per-file basis. As a result, the 
System.Windows.Markup namespace in .NET Framework 4 contains a mixture of general XAML language support 
types (from the System.XamI assembly) and types that are specific to the WPF XAML implementation (from 
WindowsBase and other WPF assemblies). Any type that was migrated to System.XamI, but existed previously in a 
WPF assembly, has type-forwarding support in version 4 of the WPF assembly. 

Workflow XAML Support Types 

Windows Workflow Foundation also provided XAML support types, and in many cases these had identical short 
names to a WPF equivalent. The following is a list of Windows Workflow Foundation XAML support types: 

• ContentPropertyAttribute 

• RuntimeNamePropertyAttribute 

• XmlnsPrefixAttribute 

These support types still exist in the Windows Workflow Foundation assemblies for .NET Framework 4 and can still 
be used for specific Windows Workflow Foundation applications; however, they should not be referenced by 
applications or frameworks that do not use Windows Workflow Foundation. 

MarkupExtension 

In the .NET Framework 3.5 and .NET Framework 3.0, the MarkupExtension class for WPF was in the WindowsBase 
assembly. A parallel class for Windows Workflow Foundation, MarkupExtension, existed in the 
System.Workflow.ComponentModel assembly. In the .NET Framework 4, the MarkupExtension class is migrated to 
the System.XamI assembly. In the .NET Framework 4, MarkupExtension is intended for any XAML extensibility 




scenario that uses .NET XAML Services, not just for those that build on specific frameworks. When possible, specific 
frameworks or user code in the framework should also build on the MarkupExtension class for XAML extension. 

MarkupExtension Supporting Service Classes 

.NET Framework 3.5 and .NET Framework 3.0 for WPF provided several services that were available to 
MarkupExtension implementers and TypeConverter implementations to support type/property usage in XAML. 
These services are the following: 

• IProvideValueTarget 

• lUriContext 

• IXamITypeResolver 


NOTE 

Another service from .NET Framework 3.5 that is related to markup extensions is the IReceiveMarkupExtension interface. 
IReceiveMarkupExtension was not migrated and is marked [obsolete] for .NET Framework 4. Scenarios that previously 
used IReceiveMarkupExtension should instead use XamISetMarkupExtensionAttribute attributed callbacks. 
AcceptedMarkupExtensionExpressionTypeAttribute is also marked [obsolete] . 


XAML Language Features 

Several XAML language features and components for WPF previously existed in the PresentationFramework 
assembly. These were implemented as a MarkupExtension subclass to expose markup extension usages in XAML 
markup. In .NET Framework 4, these exist in the System.XamI assembly so that projects that do not include WPF 
assemblies can use these XAML language-level features. WPF uses these same implementations for .NET 
Framework 4 applications. As with the other cases that are listed in this topic, the supporting types continue to 
exist in the System.Windows.Markup namespace to avoid breaking previous references. 

The following table contains a list of the XAML feature-support classes that are defined in System.XamI. 


XAML LANGUAGE FEATURE 

USAGE 

ArrayExtension 

<x:Array ... > 

NullExtension 

{x:Null} 

StaticExtension 

{x:Static . . . } 

TypeExtension 

{x:Type ...} 


Although System.XamI may not have specific support classes, the general logic for processing language features 
for the XAML language now resides in System.XamI and its implemented XAML readers and XAML writers. For 
example, x:TypeArguments is an attribute that is processed by XAML readers and XAML writers from System.XamI 
implementations; it can be noted in the XAML node stream, has handling in the default (CLR-based) XAML schema 
context, has a XAML type-system representation, and so on. As a result, the reference documentation for all XAML 
language-level features is a subtopic for XAML Services in the Desktop Guide for Windows Presentation 
Foundation (WPF). 

ValueSerializer and Supporting Classes 

The ValueSerializer class supports type conversion to a string, particularly for XAML serialization cases where 







serialization may require multiple modes or nodes in the output. In .NET Framework 3.5 and .NET Framework 3.0, 
the ValueSerializer for WPF was in the WindowsBase assembly. In the .NET Framework 4, the ValueSerializer class 
is in System.XamI and is intended for any XAML extensibility scenario, not just for those that build on WPF. 
IValueSerializerContext (a supporting service) and DateTimeValueSerializer (a specific subclass) are also migrated 
to System.XamI. 

XAML-Related Attributes 

WPF XAML included several attributes that can be applied to CLR types to indicate something about their XAML 
behavior. The following is a list of the attributes that existed in WPF assemblies in .NET Framework 3.5 and .NET 
Framework 3.0. These attributes are migrated to System.XamI in .NET Framework 4. 

• AmbientAttribute 

• ContentPropertyAttribute 

• ContentWrapperAttribute 

• DependsOnAttribute 

• MarkupExtensionReturnTypeAttribute 

• NameScopePropertyAttribute 

• RootNamespaceAttribute 

• RuntimeNamePropertyAttribute 

• TrimSurroundingWhitespaceAttribute 

• ValueSerializerAttribute 

• Whitespaces ignificantCollectionAttribute 

• XmlLangPropertyAttribute 

• XmlnsCompatibleWithAttribute 

• XmlnsDefinitionAttribute 

• XmlnsPrefixAttribute 

Miscellaneous Classes 

The IComponentConnector interface existed in WindowsBase in .NET Framework 3.5 and .NET Framework 3.0, but 
exists in System.XamI in .NET Framework 4. IComponentConnector is primarily intended for tooling support and 
XAML markup compilers. 

The INameScope interface existed in WindowsBase in .NET Framework 3.5 and .NET Framework 3.0, but exists in 
System.XamI in .NET Framework 4. INameScope defines basic operations for a XAML namescope. 

XAML-related Classes with Shared Names that Exist in WPF and 
System.XamI 

The following classes exist in both the WPF assemblies and the System.XamI assembly in .NET Framework 4: 

XamlReaden 

XamlWriten 




XamlParseExceptlon 


The WPF implementation is found in the System.Windows.Markup namespace, and PresentationFramework 
assembly. The System.XamI implementation is found in the System.XamI namespace. If you are using WPF types or 
are deriving from WPF types, you should typically use the WPF implementations of XamIReader and XamlWriter 
instead of the System.XamI implementations. For more information, see Remarks in 
System.Windows.Markup.XamI Reader and System.Windows.Markup.Xam I Writer. 

If you are including references to both WPF assemblies and System.XamI, and you also are using include 
statements for both the System.Windows.Markup and System.XamI namespaces, you may need to fully qualify the 
calls to these APIs in order to resolve the types without ambiguity. 
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WPF and Windows Forms present two different architectures for creating application interfaces. The 
System.Windows.Forms.Integration namespace provides classes that enable common interoperation scenarios. The 
two key classes that implement interoperation capabilities are WindowsFormsHost and ElementHost. This topic 
describes which interoperation scenarios are supported and which scenarios are not supported. 


NOTE 

Special consideration is given to the hybrid control scenano. A hybrid control has a control from one technology nested in a 
control from the other technology. This is also called a nested interoperation. A multilevel hybrid control\\as more than one 
level of hybrid control nesting. An example of a multilevel nested interoperation is a Windows Forms control that contains a 
WPF control, which contains another Windows Forms control. Multilevel hybrid controls are not supported. 


Hosting Windows Forms Controls in WPF 

The following interoperation scenarios are supported when a WPF control hosts a Windows Forms control: 

• The WPF control may host one or more Windows Forms controls using XAML. 

• It may host one or more Windows Forms controls using code. 

• It may host Windows Forms container controls that contain other Windows Forms controls. 

• It may host a master/detail form with a WPF master and Windows Forms details. 

• It may host a master/detail form with a Windows Forms master and WPF details. 

• It may host one or more ActiveX controls. 

• It may host one or more composite controls. 

• It may host hybrid controls using Extensible Application Markup Language (XAML). 

• It may host hybrid controls using code. 

Layout Support 

The following list describes the known limitations when the WindowsFormsHost element attempts to integrate its 

hosted Windows Forms control into the WPF layout system. 

• In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For 
example, a Windows Forms ComboBox control supports only a single height, which is defined by the 
control's font size. In a WPF dynamic layout, which assumes that elements can stretch vertically, a hosted 
ComboBox control will not stretch as expected. 

• Windows Forms controls cannot be rotated or skewed. For example, when you rotate your user interface by 
90 degrees, hosted Windows Forms controls will maintain their upright position. 

• In most cases, Windows Forms controls do not support proportional scaling. Although the overall 
dimensions of the control will scale, child controls and component elements of the control may not resize as 
expected. This limitation depends on how well each Windows Forms control supports scaling. 

• In a WPF user interface, you can change the z-order of elements to control overlapping behavior. A hosted 





Windows Forms control is drawn in a separate HWND, so it is always drawn on top of WPF elements. 

• Windows Forms controls support autoscaling based on the font size. In a WPF user interface, changing the 
font size does not resize the entire layout, although individual elements may dynamically resize. 

Ambient Properties 

Some of the ambient properties of WPF controls have Windows Forms equivalents. These ambient properties are 
propagated to the hosted Windows Forms controls and exposed as public properties on the WindowsFormsHost 
control. The WindowsFormsHost control translates each WPF ambient property into its Windows Forms 
equivalent. 

For more information, see Windows Forms and WPF Property Mapping. 

Behavior 

The following table describes interoperation behavior. 


BEHAVIOR 

SUPPORTED 

NOT SUPPORTED 

Transparency 

Windows Forms control rendering 
supports transparency. The background 
of the parent WPF control can become 
the background of hosted Windows 

Forms controls. 

Some Windows Forms controls do not 
support transparency. For example, the 
TextBox and ComboBox controls will not 
be transparent when hosted by WPF. 


BEHAVIOR 


SUPPORTED 


NOT SUPPORTED 


Tabbing Tab order for hosted Windows Forms 

controls is the same as when those 
controls are hosted in a Windows 
Forms-based application. 

Tabbing from a WPF control to a 
Windows Forms control with the TAB 
key and SHIFT+TAB keys works as 
usual. 

Windows Forms controls that have a 
TabStop property value of false do 
not receive focus when the user tabs 
through controls. 

- Each WindowsFormsHost control has 
a Tabindex value, which determines 
when that WindowsFormsHost control 
will receive focus. 

- Windows Forms controls that are 
contained inside a WindowsFormsHost 
container follow the order specified by 
the Tabindex property. Tabbing from the 
last tab index puts focus on the next 
WPF control, if one exists. If no other 
focusable WPF control exists, tabbing 
returns to the first Windows Forms 
control in the tab order. 

- Tabindex values for controls inside the 
WindowsFormsHost are relative to 
sibling Windows Forms controls that 
are contained in the 
WindowsFormsHost control. 

- Tabbing honors control-specific 
behavior. For example, pressing the TAB 
key in a TextBox control that has a 
AcceptsTab property value of true 
enters a tab in the text box instead of 
moving the focus. 


Not applicable. 




BEHAVIOR 


SUPPORTED 


NOT SUPPORTED 


Navigation with arrow keys 


Accelerators 


- Navigation with arrow keys in the 
WindowsFormsHost control is the same 
as in an ordinary Windows Forms 
container control: The UP ARROW and 
LEFT ARROW keys select the previous 
control, and the DOWN ARROW and 
RIGHT ARROW keys select the next 
control. 

- The UP ARROW and LEFT ARROW 
keys from the first control that is 
contained in the WindowsFormsHost 
control perform the same action as the 
SHIFT+TAB keyboard shortcut. If there 
is a focusable WPF control, focus moves 
outside the WindowsFormsHost 
control. This behavior differs from the 
standard ContainerControl behavior in 
that no wrapping to the last control 
occurs. If no other focusable WPF 
control exists, focus returns to the last 
Windows Forms control in the tab 
order. 

- The DOWN ARROW and RIGHT 
ARROW keys from the last control that 
is contained in the WindowsFormsHost 
control perform the same action as the 
TAB key. If there is a focusable WPF 
control, focus moves outside the 
WindowsFormsHost control. This 
behavior differs from the standard 
ContainerControl behavior in that no 
wrapping to the first control occurs. If 
no other focusable WPF control exists, 
focus returns to the first Windows 
Forms control in the tab order. 


Accelerators work as usual, except 
where noted in the "Not supported" 
column. 


Not applicable. 


Duplicate accelerators across 
technologies do not work like ordinary 
duplicate accelerators. When an 
accelerator is duplicated across 
technologies, with at least one on a 
Windows Forms control and the other 
on a WPF control, the Windows Forms 
control always receives the accelerator. 
Focus does not toggle between the 
controls when the duplicate accelerator 
is pressed. 


BEHAVIOR 


SUPPORTED 


NOT SUPPORTED 


Shortcut keys 


AcceptsReturn, AcceptsTab, and other 
control-specific behavior 


Enter and Leave Events 


Multithreading 


Security 


Accessibility 


Shortcut keys work as usual, except - Windows Forms shortcut keys that 

where noted in the "Not supported" are handled at the preprocessing stage 

column. always take precedence over WPF 

shortcut keys. For example, if you have 
a ToolStrip control with CTRL+S 
shortcut keys defined, and there is a 
WPF command bound to CTRL+S, the 
ToolStrip control handler is always 
invoked first, regardless of focus. 

- Windows Forms shortcut keys that 
are handled by the KeyDown event are 
processed last in WPF. You can prevent 
this behavior by overriding the 
Windows Forms control's IsInputKey 
method or handling the 
PreviewKeyDown event. Return true 
from the IsInputKey method, or set the 
value of the 

PreviewKeyDownEventArgs.IsInputKey 
property to true in your 
PreviewKeyDown event handler. 


Properties that change the default 
keyboard behavior work as usual, 
assuming that the Windows Forms 
control overrides the IsInputKey 
method to return true . 


Windows Forms controls that change 
default keyboard behavior by handling 
the KeyDown event are processed last 
in the host WPF control. Because these 
controls are processed last, they can 
produce unexpected behavior. 


When focus is not going to the 
containing ElementHost control, the 
Enter and Leave events are raised as 
usual when focus changes in a single 
WindowsFormsHost control. 


Enter and Leave events are not raised 
when the following focus changes 
occur: 

- From inside to outside a 
WindowsFormsHost control. 

- From outside to inside a 
WindowsFormsHost control. 

- Outside a WindowsFormsHost 
control. 

- From a Windows Forms control 
hosted in a WindowsFormsHost control 
to an ElementHost control hosted 
inside the same WindowsFormsHost. 


All varieties of multithreading are Both the Windows Forms and WPF 

supported. technologies assume a single-threaded 

concurrency model. During debugging, 
calls to framework objects from other 
threads will raise an exception to 
enforce this requirement. 


All interoperation scenarios require full No interoperation scenarios are allowed 
trust. in partial trust. 


All accessibility scenarios are supported. Not applicable. 

Assistive technology products function 

correctly when they are used for hybrid 

applications that contain both Windows 

Forms and WPF controls. 





BEHAVIOR 


SUPPORTED 


NOT SUPPORTED 


Clipboard All Clipboard operations work as usual. Not applicable. 

This includes cutting and pasting 
between Windows Forms and WPF 
controls. 


Drag-and-drop feature All drag-and-drop operations work as Not applicable. 

usual. This includes operations between 
Windows Forms and WPF controls. 


Hosting WPF Controls in Windows Forms 

The following interoperation scenarios are supported when a Windows Forms control hosts a WPF control: 

• Hosting one or more WPF controls using code. 

• Associating a property sheet with one or more hosted WPF controls. 

• Hosting one or more WPF pages in a form. 

• Starting a WPF window. 

• Hosting a master/detail form with a Windows Forms master and WPF details. 

• Hosting a master/detail form with a WPF master and Windows Forms details. 

• Hosting custom WPF controls. 

• Hosting hybrid controls. 

Ambient Properties 

Some of the ambient properties of Windows Forms controls have WPF equivalents. These ambient properties are 
propagated to the hosted WPF controls and exposed as public properties on the ElementHost control. The 
ElementHost control translates each Windows Forms ambient property to its WPF equivalent. 

For more information, see Windows Forms and WPF Property Mapping. 

Behavior 

The following table describes interoperation behavior. 

BEHAVIOR SUPPORTED NOT SUPPORTED 

Transparency WPF control rendering supports Not applicable. 

transparency. The background of the 
parent Windows Forms control can 
become the background of hosted WPF 
controls. 


Multithreading 


All varieties of multithreading are Both the Windows Forms and WPF 

supported. technologies assume a single-threaded 

concurrency model. During debugging, 
calls to framework objects from other 
threads will raise an exception to 
enforce this requirement. 


Security 


All interoperation scenarios require full No interoperation scenarios are allowed 
trust. in partial trust. 


BEHAVIOR 


SUPPORTED 


NOT SUPPORTED 


Accessibility 


All accessibility scenarios are supported. Not applicable. 


Assistive technology products function 
correctly when they are used for hybrid 
applications that contain both Windows 
Forms and WPF controls. 


Clipboard 


All Clipboard operations work as usual. Not applicable. 
This includes cutting and pasting 
between Windows Forms and WPF 
controls. 


Drag-and-drop feature 


All drag-and-drop operations work as Not applicable, 
usual. This includes operations between 
Windows Forms and WPF controls. 


See also 


• ElennentHost 

• WindowsFornnsHost 

• Walkthrough: Hosting a Windows Forms Control in WPF 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 

• Windows Forms and WPF Property Mapping 
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Interoperation between the WPF and Windows Forms requires that both technologies have the appropriate 
keyboard input processing. This topic describes how these technologies implement keyboard and message 
processing to enable smooth interoperation in hybrid applications. 

This topic contains the following subsections: 

• Modeless Forms and Dialog Boxes 

• WindowsFormsHost Keyboard and Message Processing 

• ElementHost Keyboard and Message Processing 

Modeless Forms and Dialog Boxes 

Call the EnableWindowsFormsInterop method on the WindowsFormsHost element to open a modeless form or 
dialog box from a WPF-based application. 

Call the EnableModelessKeyboardInterop method on the ElementHost control to open a modeless WPF page in a 
Windows Forms-based application. 

WindowsFormsHost Keyboard and Message Processing 

When hosted by a WPF-based application, Windows Forms keyboard and message processing consists of the 
following: 

• The WindowsFormsHost class acquires messages from the WPF message loop, which is implemented by the 
ComponentDispatcher class. 

• The WindowsFormsHost class creates a surrogate Windows Forms message loop to ensure that ordinary 
Windows Forms keyboard processing occurs. 

• The WindowsFormsHost class implements the IKeyboardInputSink interface to coordinate focus 
management with WPF. 

• The WindowsFormsHost controls register themselves and start their message loops. 

The following sections describe these parts of the process in more detail. 

Acquiring Messages from the WPF Message Loop 

The ComponentDispatcher class implements the message loop manager for WPF. The ComponentDispatcher class 
provides hooks to enable external clients to filter messages before WPF processes them. 

The interoperation implementation handles the ComponentDispatcher.ThreadFilterMessage event, which enables 
Windows Forms controls to process messages before WPF controls. 

Surrogate Windows Forms Message Loop 

By default, the System.Windows.Forms.Application class contains the primary message loop for Windows Forms 
applications. During interoperation, the Windows Forms message loop does not process messages. Therefore, this 
logic must be reproduced. The handler for the ComponentDispatcher.ThreadFilterMessage event performs the 




following steps: 

1. Filters the message using the IMessageFilter interface. 

2. Calls the Control.PreProcessMessage method. 

3. Translates and dispatches the message, if it is required. 

4. Passes the message to the hosting control, if no other controls process the message. 

I Keyboard I nputSink Implementation 

The surrogate message loop handles keyboard management. Therefore, the IKeyboardInputSink.TabInto method is 
the only IKeyboardInputSink member that requires an implementation in the WindowsFormsFlost class. 

By default, the FlwndHost class returns false for its IKeyboardInputSink.TabInto implementation. This prevents 
tabbing from a WPF control to a Windows Forms control. 

The WindowsFormsFlost implementation of the IKeyboardInputSink.TabInto method performs the following steps: 

1. Finds the first or last Windows Forms control that is contained by the WindowsFormsFlost control and that 
can receive focus. The control choice depends on traversal information. 

2. Sets focus to the control and returns true. 

3. If no control can receive focus, returns false . 

WindowsFormsFlost Registration 

When the window handle to a WindowsFormsFlost control is created, the WindowsFormsFlost control calls an 
internal static method that registers its presence for the message loop. 

During registration, the WindowsFormsFlost control examines the message loop. If the message loop has not been 
started, the ComponentDispatcher.ThreadFilterMessage event handler is created. The message loop is considered 
to be running when the ComponentDispatcher.ThreadFilterMessage event handler is attached. 

When the window handle is destroyed, the WindowsFormsFlost control removes itself from registration. 

ElementHost Keyboard and Message Processing 

When hosted by a Windows Forms application, WPF keyboard and message processing consists of the following: 

• FlwndSource, IKeyboardInputSink, and IKeyboardInputSite interface implementations. 

• Tabbing and arrow keys. 

• Command keys and dialog box keys. 

• Windows Forms accelerator processing. 

The following sections describe these parts in more detail. 

Interface Implementations 

In Windows Forms, keyboard messages are routed to the window handle of the control that has focus. In the 
ElementFlost control, these messages are routed to the hosted element. To accomplish this, the ElementFlost control 
provides an FlwndSource instance. If the ElementFlost control has focus, the FlwndSource instance routes most 
keyboard input so that it can be processed by the WPF InputManager class. 

The FlwndSource class implements the IKeyboardInputSink and IKeyboardInputSite interfaces. 

Keyboard interoperation relies on implementing the OnNoMoreTabStops method to handle TAB key and arrow key 
input that moves focus out of hosted elements. 




Tabbing and Arrow Keys 

The Windows Forms selection logic is mapped to the IKeyboardInputSink.TabInto and OnNoMoreTabStops 
methods to implement TAB and arrow key navigation. Overriding the Select method accomplishes this mapping. 

Command Keys and Dialog Box Keys 

To give WPF the first opportunity to process command keys and dialog keys, Windows Forms command 
preprocessing is connected to the TranslateAccelerator method. Overriding the Control.ProcessCmdKey method 
connects the two technologies. 

With the TranslateAccelerator method, the hosted elements can handle any key message, such as WM_KEYDOWN, 
WM_KEYUP, WM_SYSKEYDOWN, or WM_SYSKEYUR including command keys, such as TAB, ENTER, ESC, and arrow 
keys. If a key message is not handled, it is sent up the Windows Forms ancestor hierarchy for handling. 

Accelerator Processing 

To process accelerators correctly, Windows Forms accelerator processing must be connected to the WPF 
AccessKeyManager class. Additionally, all WM_CHAR messages must be correctly routed to hosted elements. 

Because the default HwndSource implementation of the TranslateChar method returns false , WM_CHAR 
messages are processed using the following logic: 

• The Control.IsInputChar method is overridden to ensure that all WM_CHAR messages are forwarded to 
hosted elements. 

• If the ALT key is pressed, the message is WM_SYSCHAR. Windows Forms does not preprocess this message 
through the IsInputChar method. Therefore, the ProcessMnemonic method is overridden to query the WPF 
AccessKeyManager for a registered accelerator. If a registered accelerator is found, AccessKeyManager 
processes it. 

• If the ALT key is not pressed, the WPF InputManager class processes the unhandled input. If the input is an 
accelerator, the AccessKeyManager processes it. The PostProcessInput event is handled for WM_CHAR 
messages that were not processed. 

When the user presses the ALT key, accelerator visual cues are shown on the whole form. To support this behavior, 
all ElementHost controls on the active form receive WM_SYSKEYDOWN messages, regardless of which control has 
focus. 

Messages are sent only to ElementHost controls in the active form. 

See also 

• EnableWindowsFormsInterop 

• EnableModelessKeyboardInterop 

• ElementHost 

• WindowsFormsHost 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 

• WPF and Win32 Interoperation 
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This topic describes how the WindowsFormsHost element interacts with the WPF layout system. 

WPF and Windows Forms support different, but similar, logic for sizing and positioning elements on a form or 
page. When you create a hybrid user interface (Ul) that hosts Windows Forms controls in WPF, the 
WindowsFormsHost element integrates the two layout schemes. 

Differences in Layout Between WPF and Windows Forms 

WPF uses resolution-independent layout. All WPF layout dimensions are specified using device-independent pixels. 
A device-independent pixel is one ninety-sixth of an inch in size and resolution-independent, so you get similar 
results regardless of whether you are rendering to a 72-dpi monitor or a 19,200-dpi printer. 

WPF is also based on dynamic layout This means that a Ul element arranges itself on a form or page according to 
its content, its parent layout container, and the available screen size. Dynamic layout facilitates localization by 
automatically adjusting the size and position of Ul elements when the strings they contain change length. 

Layout in Windows Forms is device-dependent and more likely to be static. Typically, Windows Forms controls are 
positioned absolutely on a form using dimensions specified in hardware pixels. However, Windows Forms does 
support some dynamic layout features, as summarized in the following table. 


LAYOUT FEATURE DESCRIPTION 

Autosizing Some Windows Forms controls resize themselves to display 

their contents properly. For more information, see AutoSize 
Property Overview. 

Anchoring and docking Windows Forms controls support positioning and sizing based 

on the parent container. For more information, see 
Control.Anchor and Control.Dock. 

Autoscaling Container controls resize themselves and their children based 

on the resolution of the output device or the size, in pixels, of 
the default container font. For more information, see 
Automatic Scaling in Windows Forms. 

Layout containers The FlowLayoutPanel and TableLayoutPanel controls arrange 

their child controls and size themselves according to their 
contents. 


Layout Limitations 

In general, Windows Forms controls cannot be scaled and transformed to the extent possible in WPF. The following 
list describes the known limitations when the WindowsFormsHost element attempts to integrate its hosted 
Windows Forms control into the WPF layout system. 

• In some cases, Windows Forms controls cannot be resized, or can be sized only to specific dimensions. For 
example, a Windows Forms ComboBox control supports only a single height, which is defined by the 




control's font size. In a WPF dynamic layout where elements can stretch vertically, a hosted ComboBox 
control will not stretch as expected. 

• Windows Forms controls cannot be rotated or skewed. The WindowsFormsHost element raises the 
LayoutError event if you apply a skew or rotation transformation. If you do not handle the LayoutError 
event, an InvalidOperationException is raised. 

• In most cases, Windows Forms controls do not support proportional scaling. Although the overall 
dimensions of the control will scale, child controls and component elements of the control may not resize as 
expected. This limitation depends on how well each Windows Forms control supports scaling. In addition, 
you cannot scale Windows Forms controls down to a size of 0 pixels. 

• Windows Forms controls support autoscaling, in which the form will automatically resize itself and its 
controls based on the font size. In a WPF user interface, changing the font size does not resize the entire 
layout, although individual elements may dynamically resize. 

Z-order 

In a WPF user interface, you can change the z-order of elements to control overlapping behavior. A hosted 
Windows Forms control is drawn in a separate HWND, so it is always drawn on top of WPF elements. 

A hosted Windows Forms control is also drawn on top of any Adorner elements. 

Layout Behavior 

The following sections describe specific aspects of layout behavior when hosting Windows Forms controls in WPF. 

Scaling, Unit Conversion, and Device Independence 

Whenever the WindowsFormsHost element performs operations involving WPF and Windows Forms dimensions, 
two coordinate systems are involved: device-independent pixels for WPF and hardware pixels for Windows Forms. 
Therefore, you must apply proper unit and scaling conversions to achieve a consistent layout. 

Conversion between the coordinate systems depends on the current device resolution and any layout or rendering 
transforms applied to the WindowsFormsHost element or to its ancestors. 

If the output device is 96 dpi and no scaling has been applied to the WindowsFormsHost element, one device¬ 
independent pixel is equal to one hardware pixel. 

All other cases require coordinate system scaling. The hosted control is not resized. Instead, the 
WindowsFormsHost element attempts to scale the hosted control and all of its child controls. Because Windows 
Forms does not fully support scaling, the WindowsFormsHost element scales to the degree supported by 
particular controls. 

Override the ScaleChild method to provide custom scaling behavior for the hosted Windows Forms control. 

In addition to scaling, the WindowsFormsHost element handles rounding and overflow cases as described in the 
following table. 

CONVERSION ISSUE DESCRIPTION 

Rounding WPF device-independent pixel dimensions are specified as 

double , and Windows Forms hardware pixel dimensions are 
specified as int . In cases where double -based dimensions 
are converted to int -based dimensions, the 
WindowsFormsHost element uses standard rounding, so that 
fractional values less than 0.5 are rounded down to 0. 



CONVERSION ISSUE 


DESCRIPTION 


Overflow When the WindowsFormsHost element converts from 

double values to int values, overflow is possible. Values 
that are larger than MaxValue are set to MaxValue. 


Layout-related Properties 

Properties that control layout behavior in Windows Forms controls and WPF elements are mapped appropriately 
by the WindowsFormsHost element. For more information, see Windows Forms and WPF Property Mapping. 

Layout Changes in the Hosted Control 

Layout changes in the hosted Windows Forms control are propagated to WPF to trigger layout updates. The 
InvalidateMeasure method on WindowsFormsHost ensures that layout changes in the hosted control cause the 
WPF layout engine to run. 

Continuously Sized Windows Forms Controls 

Windows Forms controls that support continuous scaling fully interact with the WPF layout system. The 
WindowsFormsHost element uses the MeasureOverride and ArrangeOverride methods as usual to size and 
arrange the hosted Windows Forms control. 

Sizing Algorithm 

The WindowsFormsHost element uses the following procedure to size the hosted control: 

1. The WindowsFormsHost element overrides the MeasureOverride and ArrangeOverride methods. 

2. To determine the size of the hosted control, the MeasureOverride method calls the hosted control's 
GetPreferredSize method with a constraint translated from the constraint passed to the MeasureOverride 
method. 

3. The ArrangeOverride method attempts to set the hosted control to the given size constraint. 

4. If the hosted control's Size property matches the specified constraint, the hosted control is sized to the 
constraint. 

If the Size property does not match the specified constraint, the hosted control does not support continuous sizing. 
For example, the MonthCalendar control allows only discrete sizes. The permitted sizes for this control consist of 
integers (representing the number of months) for both height and width. In cases such as this, the 
WindowsFormsHost element behaves as follows: 

• If the Size property returns a larger size than the specified constraint, the WindowsFormsHost element clips 
the hosted control. Height and width are handled separately, so the hosted control may be clipped in either 
direction. 

• If the Size property returns a smaller size than the specified constraint, WindowsFormsHost accepts this size 
value and returns the value to the WPF layout system. 

See also 

• ElementHost 

• WindowsFormsHost 

• Walkthrough: Arranging Windows Forms Controls in WPF 

• Arranging Windows Forms Controls in WPF Sample 

• Windows Forms and WPF Property Mapping 

• Migration and Interoperability 




Windows Forms Controls and Equivalent WPF 
Controls 
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Many Windows Forms controls have equivalent WPF controls, but some Windows Forms controls have no 
equivalents in WPF. This topic compares control types provided by the two technologies. 

You can always use interoperation to host Windows Forms controls that do not have equivalents in your WPF- 
based applications. 

The following table shows which Windows Forms controls and components have equivalent WPF control 
functionality. 


WINDOWS FORMS CONTROL 

WPF EQUIVALENT CONTROL 

REMARKS 

BindingNavigator 

No equivalent control. 


BindingSource 

CollectionViewSource 


Button 

Button 


CheckBox 

CheckBox 


CheckedListBox 

ListBox with composition. 


ColorDialog 

No equivalent control. 


ComboBox 

ComboBox 

ComboBox does not support auto- 
complete. 

ContextMenuStrip 

ContextMenu 


DataGridView 

DataGrid 


DateTimePicker 

DatePicker 


DomainUpDown 

TextBox and two RepeatButton controls. 


ErrorProvider 

No equivalent control. 


FlowLayoutPanel 

WrapPanel or StackPanel 


FolderBrowserDialog 

No equivalent control. 


FontDialog 

No equivalent control. 


Form 

Window 

Window does not support child 


windows. 




WINDOWS FORMS CONTROL 


WPF EQUIVALENT CONTROL 


REMARKS 


GroupBox 

GroupBox 


HeIpProvider 

No equivalent control. 

No FI Help. "What's This" Help is 
replaced by ToolTips. 

HScrollBar 

ScrollBar 

Scrolling is built into container controls. 

ImageList 

No equivalent control. 


Label 

Label 


LinkLabel 

No equivalent control. 

You can use the Hyperlink class to host 
hyperlinks within flow content. 

ListBox 

ListBox 


ListView 

ListView 

The ListView control provides a read¬ 
only details view. 

MaskedTextBox 

No equivalent control. 


MenuStrip 

Menu 

Menu control styling can approximate 
the behavior and appearance of the 
System.Windows.Forms.ToolStripProfessi 
onalFtenderer class. 

MonthCalendar 

Calendar 


Notifylcon 

No equivalent control. 


NumericUpDown 

TextBox and two RepeatButton controls. 


OpenFileDialog 

OpenFileDialog 

The OpenFileDialog class is a WPF 
wrapper around the Win32 control. 

PageSetupDialog 

No equivalent control. 


Panel 

Canvas 


PictureBox 

Image 


PrintDialog 

PrintDialog 


PrintDocument 

No equivalent control. 


PrintPreviewControl 

DocumentViewer 


PrintPreviewDialog 

No equivalent control. 


ProgressBar 

ProgressBar 



WINDOWS FORMS CONTROL 


WPF EQUIVALENT CONTROL 


REMARKS 


PropertyGrid 

No equivalent control. 


RadioButton 

RadioButton 


RichTextBox 

RichTextBox 


SaveFileDialog 

SaveFileDialog 

The SaveFileDialog class is a WPF 
wrapper around the Win32 control. 

ScrollableControl 

ScrollViewer 


Sound Player 

MediaPlayer 


SplitContainer 

GridSplitter 


StatusStrip 

StatusBar 


TabControl 

TabControl 


TableLayoutPanel 

Grid 


TextBox 

TextBox 


Timer 

DispatcherTimer 


ToolStrip 

ToolBar 


ToolStripContainer 

ToolBar with composition. 


ToolStripDropDown 

ToolBar with composition. 


ToolStripDropDownMenu 

ToolBar with composition. 


ToolStripPanel 

ToolBar with composition. 


ToolTip 

ToolTip 


TrackBar 

Slider 


TreeView 

TreeView 


UserControl 

UserControl 


VScrollBar 

ScrollBar 

Scrolling is built into container controls. 


WINDOWS FORMS CONTROL 


WPF EQUIVALENT CONTROL 


REMARKS 


WebBrowser Frame, 

System.Windows.Controls.WebBrowser 


See also 

• ElementHost 

• WindowsFormsHost 

• WPF Designer for Windows Forms Developers 

• Walkthrough: Hosting a Windows Forms Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 

• Migration and Interoperability 


The Frame control can host HTML 
pages. 

Starting in the .NET Framework 3.5 SP1, 
the 

System.Windows.Controls.WebBrowser 
control can host HTML pages and also 
backs the Frame control. 


Windows Forms and WPF Property Mapping 
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The Windows Forms and WPF technologies have two similar but different property models. Property mapping 
supports interoperation between the two architectures and provides the following capabilities: 

• Makes it easy to map relevant property changes in the host environment to the hosted control or element. 

• Provides default handling for mapping the most commonly used properties. 

• Allows easy removal, overriding, or extending of default properties. 

• Ensures that property value changes on the host are automatically detected and translated to the hosted 
control or element. 


NOTE 

Property-change events are not propagated up the hosting control or element hierarchy. Property translation is not 
performed if the local value of a property does not change because of direct setting, styles, inheritance, data binding, or 
other mechanisms that change the value of the property. 


Use the PropertyMap property on the WindowsFormsFlost element and the PropertyMap property on 
ElementHost control to access property mapping. 

Property Mapping with the WindowsFormsHost Element 

The WindowsFormsFlost element translates default WPF properties to their Windows Forms equivalents using 
the following translation table. 

WINDOWS PRESENTATION 

FOUNDATION HOSTING WINDOWS FORMS INTEROPERATION BEHAVIOR 





WINDOWS PRESENTATION 
EOUNDATION HOSTING 


WINDOWS FORMS 


INTEROPERATION BEHAVIOR 


Background 

(System.Windows.Media.Brush) 


Cursor 


FlowDirection 

(System.Windows.FlowDirection) 


BackColor The WindowsFormsHost element sets 

the BackColor property of the hosted 

(System.Drawing.Color) control and the Backgroundimage 

property of the hosted control. 
Mapping is performed by using the 
following rules: 

- If Background is a solid color, it is 
converted and used to set the 
BackColor property of the hosted 
control. The BackColor property is not 
set on the hosted control, because the 
hosted control can inherit the value of 
the BackColor property. Note: The 
hosted control does not support 
transparency. Any color assigned to 
BackColor must be fully opaque, with 
an alpha value of OxFF. 

- If Background is not a solid color, the 
WindowsFormsHost control creates a 
bitmap from the Background property. 
The WindowsFormsHost control 
assigns this bitmap to the 
Backgroundimage property of the 
hosted control. This provides an effect 
which is similar to transparency. Note: 
You can override this behavior or you 
can remove the Background property 
mapping. 


Cursor If the default mapping has not been 

reassigned, WindowsFormsHost control 
traverses its ancestor hierarchy until it 
finds an ancestor with its Cursor 
property set. This value is translated to 
the closest corresponding Windows 
Forms cursor. 

If the default mapping for the 
ForceCursor property has not been 
reassigned, the traversal stops on the 
first ancestor with ForceCursor set to 
true . 


RightToLeft LeftToRight maps to No. 

(System.Windows.Forms.RightToLeft) RightToLeft maps to Yes. 

Inherit is not mapped. 


FlowDirection.RightToLeft maps to 
RightToLeft.Yes. 



WINDOWS PRESENTATION 
FOUNDATION HOSTING 


WINDOWS FORMS 


INTEROPERATION BEHAVIOR 


FontStyle 

Style on the hosted control's 

System.Drawing.Font 

The set of WPF properties is translated 
into a corresponding Font. When one 
of these properties changes, a new 

Font is created. For Normal: Italic is 
disabled. For Italic or Oblique: Italic is 
enabled. 

FontWeight 

Style on the hosted control's 

The set of WPF properties is translated 


System.Drawing.Font 

into a corresponding Font. When one 
of these properties changes, a new 

Font is created. For Black, Bold, 
DemiBold, ExtraBold, Heavy, Medium, 
SemiBold, or UltraBold: Bold is enabled. 
For ExtraLight, Light, Normal, Regular, 
Thin, or UltraLight: Bold is disabled. 

FontFamily 

Font 

The set of WPF properties is translated 
into a corresponding Font. When one 

FontSize 

(System.Drawing.Font) 

of these properties changes, a new 

Font is created. The hosted Windows 

FontStretch 

FontStyle 


Forms control resizes based on the font 

size. 

Font size in WPF is expressed as one 

FontWeight 


ninety-sixth of an inch, and in Windows 
Forms as one seventy-second of an 
inch. The corresponding conversion is: 

Windows Forms font size = WPF font 
size * 72.0/96.0. 

Foreground 

ForeColor 

The Foreground property mapping is 
performed by using the following rules: 

(System.Windows.Media.Brush) 

(System.Drawing.Color) 

- If Foreground is a SolidColorBrush, 
use Color for ForeColor. 

- If Foreground is a GradientBrush, use 
the color of the GradientStop with the 
lowest offset value for ForeColor. 

- For any other Brush type, leave 
ForeColor unchanged. This means the 
default is used. 

IsEnabled 

Enabled 

When IsEnabled is set, 
WindowsFormsHost element sets the 
Enabled property on the hosted 
control. 

Padding 

Padding 

All four values of the Padding property 
on the hosted Windows Forms control 

are set to the same Thickness value. 

- Values greater than MaxValue are set 
to MaxValue. 

- Values less than MinValue are set to 

MinValue. 


WINDOWS PRESENTATION 
EOUNDATION HOSTING 


WINDOWS FORMS 


INTEROPERATION BEHAVIOR 


Visibility Visible - Visible maps to Visible = true. The 

hosted Windows Forms control is 
visible. Explicitly setting the Visible 
property on the hosted control to 


control is not drawn, and its area is 
collapsed. 

- Hidden : The hosted Windows Forms 
control occupies space in the layout, 
but is not visible. In this case, the 
Visible property is set to true . 
Explicitly setting the Visible property on 
the hosted control to false is not 
recommended. 


false is not recommended. 

- Collapsed maps to Visible = true or 
false . The hosted Windows Forms 


Attached properties on container elements are fully supported by the WindowsFormsHost element. 

For more information, see Walkthrough: Mapping Properties Using the WindowsFormsHost Element. 

Updates to Parent Properties 

Changes to most parent properties cause notifications to the hosted child control. The following list describes 
properties which do not cause notifications when their values change. 

• Background 

• Cursor 

• ForceCursor 

• Visibility 

For example, if you change the value of the Background property of the WindowsFormsHost element, the 
BackColor property of the hosted control does not change. 

Property Mapping with the ElementHost Control 

The following properties provide built-in change notification. Do not call the OnPropertyChanged method when 
you are mapping these properties: 

• AutoSize 

• BackColor 

• Backgroundimage 

• BackgroundImageLayout 

• BindingContext 

• CausesValidation 

• ContextMenu 

• ContextMenuStrip 


• Cursor 







• Dock 


• Enabled 

• Font 

• ForeColor 

• Location 

• Margin 

• Padding 

• Parent 

• Region 

• RightToLeft 

• Size 

• Tabindex 

• TabStop 

• Text 

• Visible 

The ElementHost control translates default Windows Forms properties to their WPF equivalents by using the 
following translation table. 

For more information, see Walkthrough: Mapping Properties Using the ElementHost Control. 


WINDOWS FORMS HOSTING 


WINDOWS PRESENTATION 
EOUNDATION 


INTEROPERATION BEHAVIOR 


BackColor 


Background 


Setting this property forces a repaint 
with an ImageBrush. If the 
BackColorTransparent property is set to 
false (the default value), this 
ImageBrush is based on the 
appearance of the ElementHost control, 
including its BackColor, 
Backgroundimage, 
BackgroundImageLayout properties, 
and any attached paint handlers. 


(System.Drawing.Color) 


(System.Windows.Media.Brush) on the 
hosted element 


If the BackColorTransparent property is 
set to true , the ImageBrush is based 
on the appearance of the ElementHost 
control's parent, including the parent's 
BackColor, Backgroundimage, 
BackgroundImageLayout properties, 
and any attached paint handlers. 


Backgroundimage 


Background 


Setting this property causes the same 
behavior described for the BackColor 


(System.Drawing.lmage) 


(System.Windows.Media.Brush) on the mapping, 

hosted element 




WINDOWS FORMS HOSTING 

WINDOWS PRESENTATION 

EOUNDATION 

INTEROPERATION BEHAVIOR 

Backgrou ndl mageLayout 

Background 

(System.Windows.Media.Brush) on the 
hosted element 

Setting this property causes the same 
behavior described for the BackColor 
mapping. 

Cursor 

(System.Windows.Forms.Cursor) 

Cursor 

(System.Windows.Input.Cursor) 

The Windows Forms standard cursor is 
translated to the corresponding WPF 
standard cursor. If the Windows Forms 
is not a standard cursor, the default is 
assigned. 

Enabled 

IsEnabled 

When Enabled is set, the ElementHost 
control sets the IsEnabled property on 
the hosted element. 

Font 

(System.Drawing.Font) 

FontFamily 

FontSize 

FontStretch 

FontStyle 

FontWeight 

The Font value is translated into a 
corresponding set of WPF font 
properties. 

Bold 

FontWeight on hosted element 

If Bold is true , FontWeight is set to 

Bold. 



If Bold is false , FontWeight is set to 

Normal. 

Italic 

FontStyle on hosted element 

If Italic is true , FontStyle is set to 

Italic. 



If Italic is false , FontStyle is set to 

Normal. 

Strikeout 

TextDecorations on hosted element 

Applies only when hosting a TextBlock 
control. 

Underline 

TextDecorations on hosted element 

Applies only when hosting a TextBlock 
control. 

RightToLeft 

FlowDirection 

No maps to LeftToRight. 

(System.Windows.Forms.RightToLeft) 

(FlowDirection) 

Yes maps to RightToLeft. 

Visible 

Visibility 

The ElementHost control sets the 


Visibility property on the hosted 
element by using the following rules: 


- Visible = true maps to Visible. 

- Visible = false maps to Hidden. 


See also 






ElementHost 

WindowsFormsHost 

WPF and Win32 Interoperation 

WPF and Windows Forms Interoperation 

Walkthrough: Mapping Properties Using the WindowsFormsHost Element 
Walkthrough: Mapping Properties Using the ElementHost Control 


Troubleshooting Hybrid Applications 
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This topic lists some common problems that can occur when authoring hybrid applications, which use both WPF 
and Windows Forms technologies. 

Overlapping Controls 

Controls may not overlap as you would expect. Windows Forms uses a separate HWND for each control. WPF uses 
one HWND for all content on a page. This implementation difference causes unexpected overlapping behaviors. 

A Windows Forms control hosted in WPF always appears on top of the WPF content. 

WPF content hosted in an ElementHost control appears at the z-order of the ElementHost control. It is possible to 
overlap ElementHost controls, but the hosted WPF content does not combine or interact. 

Child Property 

The WindowsFormsHost and ElementHost classes can host only a single child control or element. To host more 
than one control or element, you must use a container as the child content. For example, you could add Windows 
Forms button and check box controls to a System.Windows.Forms.Panel control, and then assign the panel to a 
WindowsFormsHost control's Child property. However, you cannot add the button and check box controls 
separately to the same WindowsFormsHost control. 

Scaling 

WPF and Windows Forms have different scaling models. Some WPF scaling transformations are meaningful to 
Windows Forms controls, but others are not. For example, scaling a Windows Forms control to 0 will work, but if 
you try to scale the same control back to a non-zero value, the control's size remains 0. For more information, see 
Layout Considerations for the WindowsFormsHost Element. 

Adapter 

There may be confusion when working the WindowsFormsHost and ElementHost classes, because they include a 
hidden container. Both the WindowsFormsHost and ElementHost classes have a hidden container, called an adapter, 
which they use to host content. For the WindowsFormsHost element, the adapter derives from the 
System.Windows.Forms.ContainerControl class. For the ElementHost control, the adapter derives from the 
DockPanel element. When you see references to the adapter in other interoperation topics, this container is what is 
being discussed. 

Nesting 

Nesting a WindowsFormsHost element inside an ElementHost control is not supported. Nesting an ElementHost 
control inside a WindowsFormsHost element is also not supported. 

Focus 

Focus works differently in WPF and Windows Forms, which means that focus issues may occur in a hybrid 
application. For example, if you have focus inside a WindowsFormsHost element, and you either minimize and 
restore the page or show a modal dialog box, focus inside the WindowsFormsHost element may be lost. The 




WindowsFormsHost element still has focus, but the control inside it may not. 

Data validation is also affected by focus. Validation works in a WindowsFormsHost element, but it does not work as 
you tab out of the WindowsFormsHost element, or between two different WindowsFormsHost elements. 

Property Mapping 

Some property mappings require extensive interpretation to bridge dissimilar implementations between the WPF 
and Windows Forms technologies. Property mappings enable your code to react to changes in fonts, colors, and 
other properties. In general, property mappings work by listening for either PropertyChanged events or 
OnPropertyCnanged calls, and setting appropriate properties on either the child control or its adapter. For more 
information, see Windows Forms and WPF Property Mapping. 

Layout-related Properties on Hosted Content 

When the WindowsFormsHost.Child or ElementHost.Child property is assigned, several layout-related properties 
on the hosted content are set automatically. Changing these content properties can cause unexpected layout 
behaviors. 

Your hosted content is docked to fill the WindowsFormsHost and ElementHost parent. To enable this fill behavior, 
several properties are set when you set the child property. The following table lists which content properties are set 
by the ElementHost and WindowsFormsHost classes. 


HOST CLASS 

CONTENT PROPERTIES 

ElementHost 

Height 


Width 


Margin 


VerticalAlignment 


HorizontalAlignment 

WindowsFormsHost 

Margin 


Dock 


AutoSize 


Location 


MaximumSize 


Do not set these properties directly on the hosted content. For more information, see Layout Considerations for the 
WindowsFormsHost Element. 

Navigation Applications 

Navigation applications may not maintain user state. The WindowsFormsHost element recreates its controls when 
it is used in a navigation application. Recreating child controls occurs when the user navigates away from the page 
hosting the WindowsFormsHost element and then returns to it. Any content that has been typed in by the user will 
be lost. 


Message Loop Interoperation 


When working with Windows Forms message loops, messages may not be processed as expected. The 
EnableWindowsFormsInterop method is called by the WindowsFormsHost constructor. This method adds a 
message filter to the WPF message loop. This filter calls the Control.PreProcessMessage method if a 
System.Windows.Forms.Control was the target of the message and translates/dispatches the message. 

If you show a Window in a Windows Forms message loop with Application.Run, you cannot type anything unless 
you call the EnableModelessKeyboardInterop method. The EnableModelessKeyboardInterop method takes a 
Window and adds a System.Windows.Forms.IMessageFilter, which reroutes key-related messages to the WPF 
message loop. For more information, see Windows Forms and WPF Interoperability Input Architecture. 

Opacity and Layering 

The FlwndHost class does not support layering. This means that setting the Opacity property on the 
WindowsFormsFlost element has no effect, and no blending will occur with other WPF windows which have 
AllowsTransparency set to true. 

Dispose 

Not disposing classes properly can leak resources. In your hybrid applications, make sure that the 
WindowsFormsFlost and ElementHost classes are disposed, or you could leak resources. Windows Forms disposes 
ElementFlost controls when its non-modal Form parent closes. WPF disposes WindowsFormsHost elements when 
your application shuts down. It is possible to show a WindowsFormsHost element in a Window in a Windows 
Forms message loop. In this case, your code may not receive notification that your application is shutting down. 

Enabling Visual Styles 

Microsoft Windows XP visual styles on a Windows Forms control may not be enabled. The 
Application.EnableVisualStyles method is called in the template for a Windows Forms application. Although this 
method is not called by default, if you use Visual Studio to create a project, you will get Microsoft Windows XP 
visual styles for controls, if version 6.0 of Comctl32.dll is available. You must call the EnableVisualStyles method 
before handles are created on the thread. For more information, see How to: Enable Visual Styles in a Hybrid 
Application. 

Licensed Controls 

Licensed Windows Forms controls that display licensing information in a message box to the user might cause 
unexpected behavior for a hybrid application. Some licensed controls show a dialog box in response to handle 
creation. For example, a licensed control might inform the user that a license is required, or that the user has three 
remaining trial uses of the control. 

The WindowsFormsHost element derives from the HwndHost class, and the child control's handle is created inside 
the BuildWindowCore method. The HwndHost class does not allow messages to be processed in the 
BuildWindowCore method, but displaying a dialog box causes messages to be sent. To enable this licensing 
scenario, call the Control.CreateControl method on the control before assigning it as the WindowsFormsHost 
element's child. 

WPF Designer 

You can design your WPF content by using the WPF Designer for Visual Studio. The following sections list some 
common problems that can occur when authoring hybrid applications with the WPF Designer. 

BackColorTransparent is ignored at design time 

The BackColorTransparent property might not work as expected at design time. 



If a WPF control is not on a visible parent, the WPF runtime ignores the BackColorTransparent value. The reason 
that BackColorTransparent might be ignored is because ElementHost object is created in a separate AppDomain. 
However, when you run the application, BackColorTransparent does work as expected. 

Design-time Error List appears when the obj folder is deleted 

If the obj folder is deleted, the Design-time Error List appears. 

When you design using ElementHost, the Windows Forms Designer uses generated files in the Debug or Release 
folder within your project's obj folder. If you delete these files, the Design-time Error List appears. To fix this 
problem, rebuild your project. For more information, see Design-Time Errors in the Windows Forms Designer. 

ElementHost and I ME 

WPF controls hosted in an ElementHost currently do not support the ImeMode property. Changes to ImeMode wi 
be ignored by the hosted controls. 

See also 

• ElementHost 

• WindowsFormsHost 

• Interoperability in the WPF Designer 

• Windows Forms and WPF Interoperability Input Architecture 

• How to; Enable Visual Styles in a Hybrid Application 

• Layout Considerations for the WindowsFormsHost Element 

• Windows Forms and WPF Property Mapping 

• Design-Time Errors in the Windows Forms Designer 

• Migration and Interoperability 


Walkthrough: Hosting a Windows Fornns Control in 
WPF 
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WPF provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms 
controls on your WPF pages. For example, you may have a substantial investment in existing Windows Forms 
controls, or you may have a Windows Forms control that provides unique functionality. 

This walkthrough shows you how to host a Windows Forms System.Windows.Forms.MaskedTextBox control on a 
WPF page by using code. 

For a complete code listing of the tasks shown in this walkthrough, see Hosting a Windows Forms Control in WPF 
Sample. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Hosting the Windows Forms Control 

To host the MaskedTextBox control 

1. Create a WPF Application project named HostingWfinWpf . 

2. Add references to the following assemblies. 

• WindowsFormsIntegration 

• System.Windows.Forms 

3. Open MainWindow.xamI in the WPF Designer. 

4. Name the Grid element gnidi . 

<Grid Name="gr'idl"> 

</Gr'id> 

5. In Design view or XAML view, select the Window element. 

6. In the Properties window, click the Events tab. 

7. Double-click the Loaded event. 


8. Insert the following code to handle the Loaded event. 







private void Window_Loaded(object sendetj RoutedEventArgs e) 

{ 

// Create the interop host control. 

System.Windows.Forms.Integration.WindowsFormsHost host = 

new System.Windows. Forms.Integration.WindowsFormsFlost(); 

// Create the MaskedTextBox control. 

MaskedTextBox mthDate = new MaskedTextBox("00/00/0000"); 

// Assign the MaskedTextBox control as the host control's child, 
host.Child = mthDate; 

// Add the interop host control to the Grid 
// control's collection of child controls, 
this.gridl.Children.Add(host); 

} 


Private Suh Window_Loaded(ByVal sender As Object^ ByVal e As RoutedEventArgs) 

' Create the interop host control. 

Dim host As New System.Windows.Forms.Integration.WindowsFormsHost() 

' Create the MaskedTextBox control. 

Dim mthDate As New MaskedTextBox("00/00/0000") 


' Assign the MaskedTextBox control as the host control's 

host.Child = mthDate 

child. 

' Add the interop host control to the Grid 

' control's collection of child controls. 

Me.gridl.Children.Add(host) 


End Sub 



9. At the top of the file, add the following imports or using statement. 


using System.Windows.Forms; 



See also 

• ElementHost 

• WindowsFormsHost 

• Design XAML in Visual Studio 

• Walkthrough: Hosting a Windows Forms Control in WPF by Using XAML 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 

• Windows Forms Controls and Equivalent WPF Controls 

• Hosting a Windows Forms Control in WPF Sample 






Walkthrough: Hosting a Windows Forms Control in 
WPF by Using XAML 
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WPF provides many controls with a rich feature set. However, you may sometimes want to use Windows Forms 
controls on your WPF pages. For example, you may have a substantial investment in existing Windows Forms 
controls, or you may have a Windows Forms control that provides unique functionality. 

This walkthrough shows you how to host a Windows Forms System.Windows.Forms.MaskedTextBox control on a 
WPF page by using XAML. 

For a complete code listing of the tasks shown in this walkthrough, see Hosting a Windows Forms Control in WPF 
by Using XAML Sample. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Hosting the Windows Forms Control 

To host the MaskedTextBox control 

1. Create a WPF Application project named HostingWfinWpfWithxami . 

2. Add references to the following assemblies. 

• WindowsFormsIntegration 

• System.Windows.Forms 

3. Open MainWindow.xamI in the WPF Designer. 

4. In the Window element, add the following namespace mapping. The wf namespace mapping establishes a 
reference to the assembly that contains the Windows Forms control. 

xmlns :wf="clr-namespace:System.Windows.Formsjassembly=System.Windows.Forms" 

5. In the Grid element add the following XAML. 

The MaskedTextBox control is created as a child of the WindowsFormsHost control. 

<Grid> 

<WindowsFormsHost> 

<wf:MaskedTextBox x:Name="mtbDate" Mask="00/00/0000"/> 

</WindowsFormsHost> 

</Grid> 

6. Press F5 to build and run the application. 


See also 








ElementHost 

WindowsFormsHost 

Design XAML in Visual Studio 

Walkthrough: Hosting a Windows Fornns Control in WPF 
Walkthrough: Hosting a Windows Forms Composite Control in WPF 
Walkthrough: Hosting a WPF Composite Control in Windows Forms 
Windows Forms Controls and Equivalent WPF Controls 
Hosting a Windows Forms Control in WPF by Using XAML Sample 


Walkthrough: Hosting a Windows Forms Composite 
Control in WPF 
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Windows Presentation Foundation (WPF) provides a rich environment for creating applications. However, when 
you have a substantial investment in Windows Forms code, it can be more effective to reuse at least some of that 
code in your WPF application rather than to rewrite it from scratch. The most common scenario is when you have 
existing Windows Forms controls. In some cases, you might not even have access to the source code for these 
controls. WPF provides a straightforward procedure for hosting such controls in a WPF application. For example, 
you can use WPF for most of your programming while hosting your specialized DataGridView controls. 

This walkthrough steps you through an application that hosts a Windows Forms composite control to perform 
data entry in a WPF application. The composite control is packaged in a DLL. This general procedure can be 
extended to more complex applications and controls. This walkthrough is designed to be nearly identical in 
appearance and functionality to Walkthrough: Hosting a WPF Composite Control in Windows Forms. The primary 
difference is that the hosting scenario is reversed. 

The walkthrough is divided into two sections. The first section briefly describes the implementation of the 
Windows Forms composite control. The second section discusses in detail how to host the composite control in a 
WPF application, receive events from the control, and access some of the control's properties. 

Tasks illustrated in this walkthrough include: 

• Implementing the Windows Forms composite control. 

• Implementing the WPF host application. 

For a complete code listing of the tasks illustrated in this walkthrough, see Hosting a Windows Forms Composite 
Control in WPF Sample. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Implementing the Windows Forms Composite Control 

The Windows Forms composite control used in this example is a simple data-entry form. This form takes the 
user's name and address and then uses a custom event to return that information to the host. The following 
illustration shows the rendered control. 


The following image shows a Windows Forms composite control: 




Simple Windows Forms Control 


Name | 

Street Address | 

City I State r“ 

Zip I 

OK I Cancel | 

Creating the Project 

To start the project: 

1. Launch Visual Studio, and open the New Project dialog box. 

2. In the Window category, select the Windows Forms Control Library template. 

3. Name the new project MyControis . 

4. For the location, specify a conveniently named top-level folder, such as wpfHostingWindowsFor’msContr'oi . 

Later, you will put the host application in this folder. 

5. Click OK to create the project. The default project contains a single control named userContr’oii . 

6. In Solution Explorer, rename userContr'oii to MyContr’oii . 

Your project should have references to the following system DLLs. If any of these DLLs are not included by 
default, add them to the project. 

• System 

• System.Data 

• System.Drawing 

• System.Windows.Forms 

• System.Xml 

Adding Controls to the Form 

To add controls to the form: 

• Open MyControii in the designer. 

Add five Label controls and their corresponding TextBox controls, sized and arranged as they are in the preceding 
illustration, on the form. In the example, the TextBox controls are named: 


txtName 




txtAddness 



txtCity 




txtState 



txtZip 



Add two Button controls labeled OK and Cancel. In the example, the button names are btnOK and btnCancei , 
respectively. 






















Implementing the Supporting Code 

Open the form in code view. The control returns the collected data to its host by raising the custom 
onButtonciick event. The data is contained in the event argument object. The following code shows the event 
and delegate declaration. 

Add the following code to the MyControii class. 

public delegate void MyControlEventHandler(object sender, MyControlEventArgs args); 
public event MyControlEventHandler OnButtonClick; 


Public Delegate Sub MyControlEventHandler(ByVal sender As Object, ByVal args As MyControlEventArgs) 
Public Event OnButtonClick As MyControlEventHandler 

The MyControlEventArgs class contains the information to be returned to the host. 

Add the following class to the form. 








public class MyControlEventAngs : EventAngs 

{ 

private string _Name; 
private string _StreetAddress; 
private string _City; 
private string _State; 
private string _Zip; 
private bool _IsOK; 

public MyControlEventArgs(bool result^ 

string name, 
string address 
string city, 
string state, 
string zip) 

{ 

_IsOK = result; 

_Name = name; 

_StreetAddress = address; 

_City = city; 

_State = state; 

_Zip = zip; 

} 

public string MyName 

{ 

get { return _Name; } 
set { _Name = value; } 

} 

public string MyStreetAddress 

{ 

get { return _StreetAddress; } 
set { _StreetAddress = value; } 

} 

public string MyCity 

{ 

get { return _City; } 
set { _City = value; } 

} 

public string MyState 

{ 

get { return _State; } 
set { _State = value; } 

} 

public string MyZip 

{ 

get { return _Zip; } 
set { _Zip = value; } 

} 

public bool IsOK 

{ 

get { return _IsOK; } 
set { _IsOK = value; } 

} 


Public Class MyControlEventAngs 
Inherits EventArgs 
Private _Name As String 
Private _StreetAddress As String 
Private _City As String 
Private _State As String 
Private _Zip As String 
Private IsOK As Boolean 


Public Sub New(By\/al result As Boolean, ByVal name As String, ByVal address As String, ByVal city As 
String, ByVal state As String, ByVal zip As String) 

_IsOK = result 

_Name = name 

_StreetAddress = address 

_Clty = city 

_State = state 

_2ip = zip 

End Sub 


Public Property MyName() As String 
Get 

Return _Name 
End Get 
Set 

_Name = value 
End Set 
End Property 

Public Property MyStreetAddress() As String 
Get 

Return _StreetAddress 
End Get 
Set 

_StreetAddress = value 
End Set 
End Property 

Public Property MyCityO As String 
Get 

Return _City 
End Get 
Set 

_City = value 
End Set 
End Property 

Public Property MyState() As String 
Get 

Return _State 
End Get 
Set 

_State = value 
End Set 
End Property 

Public Property MyZipO As String 
Get 

Return _Zip 
End Get 
Set 

_Zip = value 
End Set 
End Property 

Public Property IsOK() As Boolean 
Get 

Return _IsOK 
End Get 
Set 

_IsOK = value 
End Set 
End Property 
End Class 


When the user clicks the OK or Cancel button, the Click event handlers create a MyControiEventAngs object that 
contains the data and raises the onButtonciick event. The only difference between the two handlers is the event 
argunnent's isok property. This property enables the host to determine which button was clicked. It is set to 
true for the OK button, and false for the Cancel button. The following code shows the two button handlers. 

Add the following code to the MyControii class. 

private void btnOK_Click(object sender. System.EventArgs e) 

{ 

MyControlEventArgs retvals = new MyControlEventArgs(true, 

txtName.Text, 
txtAdd res s.Text, 
txtCity.Text, 
txtState.Text, 
txtZip.Text)j 

OnButtonClick(this, retvals); 

} 

private void btnCancel_Click(object sender. System.EventArgs e) 

{ 

MyControlEventArgs retvals = new MyControlEventArgs(false, 

txtName.Text, 
txtAddress.Text, 
txtCity.Text, 
txtState.Text, 
txtZip.Text); 

OnButtonClick(this, retvals); 

} 


Private Sub btnOK_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles btnOK.Click 

Dim retvals As New MyControlEventArgs(True, txtName.Text, txtAddress.Text, txtCity.Text, txtState.Text, 
txtZip.Text) 

RaiseEvent OnButtonClick(Me, retvals) 

End Sub 

Private Sub btnCancel_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles btnCancel.Click 

Dim retvals As New MyControlEventArgs(False, txtName.Text, txtAddress.Text, txtCity.Text, txtState.Text, 
txtZip.Text) 

RaiseEvent OnButtonClick(Me, retvals) 

End Sub 


Giving the Assembly a Strong Name and Building the Assembly 

For this assembly to be referenced by a WPF application, it must have a strong name. To create a strong name, 
create a key file with Sn.exe and add it to your project. 

1. Open a Visual Studio command prompt. To do so, click the Start menu, and then select All 
Programs/Microsoft Visual Studio 2010/Visual Studio Tools/Visual Studio Command Prompt. 
This launches a console window with customized environment variables. 

2. At the command prompt, use the cd command to go to your project folder. 

3. Generate a key file named MyControls.snk by running the following command. 

Sn.exe -k MyControls.snk 

4. To include the key file in your project, right-click the project name in Solution Explorer and then click 











Properties. In the Project Designer, click the Signing tab, select the Sign the assembly check box and 
then browse to your key file. 

5. Build the solution. The build will produce a DLL named MyControls.dll. 

Implementing the WPF Host Application 

The WPF host application uses the WindowsFormsHost control to host MyControii . The application handles the 
onButtonciick event to receive the data from the control. It also has a collection of option buttons that enable 
you to change some of the control's properties from the WPF application. The following illustration shows the 
finished application. 

The following image shows the complete application, including the control embedded in the WPF application: 



Creating the Project 

To start the project: 

1. Open Visual Studio, and select New Project. 

2. In the Window category, select the WPF Application template. 

3. Name the new project wpfHost . 

4. For the location, specify the same top-level folder that contains the MyControls project. 

5. Click OK to create the project. 

You also need to add references to the DLL that contains MyControii and other assemblies. 

1. Right-click the project name in Solution Explorer and select Add Reference. 

2. Click the Browse tab, and browse to the folder that contains MyControls.dll. For this walkthrough, this 
folder is MyControls\bin\Debug. 




















3. Select MyControls.dll, and then click OK. 


4. Add a reference to the WindowsFormsIntegration assembly, which is named 
WindowsFormslntegration.dll. 

Implementing the Basic Layout 

The user interface (Ul) of the host application is implemented in MainWindow.xaml. This file contains Extensible 
Application Markup Language (XAML) markup that defines the layout, and hosts the Windows Forms control. The 
application is divided into three regions: 

• The Control Properties panel, which contains a collection of option buttons that you can use to modify 
various properties of the hosted control. 

• The Data from Control panel, which contains several TextBlock elements that display the data returned 
from the hosted control. 

• The hosted control itself. 

The basic layout is shown in the following XAML. The markup that is needed to host MyControii is omitted from 
this example, but will be discussed later. 

Replace the XAML in MainWindow.xaml with the following. If you are using Visual Basic, change the class to 

x:Class="MainWindow" . 

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

X:Class="WpfHost.MainWindow" 

xmlns:mcl="clr-namespace:MyControls;assembly=MyControls" 

Loaded="Init"> 

<Docl<Panel> 

cDockPanel.Resources> 

<Style x:Key="inlineText" TargetType="{x:Type Inline}"> 

<Setter Property="FontWeight" Value="Normal"/> 

</Style> 

<Style x:Key="titleText" TargetType="{x:Type TextBlock}"> 

<Setter Property="DockPanel.Dock" Value="Top"/> 

<Setter Property="FontWeight" Value="Bold"/> 

<Setter Property="Margin" Value="10j5jl0,0"/> 

</Style> 

</DockPanel.Resources> 

<StackPanel Orlentation="Vertical" 

DockPanel.Dock="Left" 

Background="Bisque" 

Width="250"> 

<TextBlock Hargin="10j10,10,10" 

FontWeight="Bold" 

FontSize="12">Control Properties</TextBlock> 

<TextBlock Style="{StaticResource titleText}">Background Color</TextBlock> 

<StackPanel Margin="10,10,10,10"> 

<RadioButton Name="rdbtnOriginalBackColor" 

IsChecked="True" 

Cllck="BackColorChanged">Original</RadioButton> 

<RadioButton Name="rdbtnBackGreen" 

Click="BackColorChanged">LightGreen</RadioButton> 

<RadioButton Name="rdbtnBackSalmon" 

Click="BackColorChanged">LightSalmon</RadioButton> 

</StackPanel> 

<TextBlock Style="{StaticResource titleText}">Foreground Color</TextBlock> 

<StackPanel Margin="10,10,10,10"> 

<RadioButton Name="rdbtnOrlginalForeColor" 

IsChecked="True" 




LiicK='l-oreLoiorLriangea' >uriginal</Kaaiotiutton> 

<RadioButton Name="rdbtnForeRed" 

Click="ForeColorChanged">Red</RadioButton> 

<RadioButton Name="rdbtnFor'eYellow" 

Click="ForeColorChanged">Yellow</RadioButton> 

</StackPanel> 

<TextBlock Style="{StaticResour'ce titleText}">Font Family</TextBlock> 
<StackPanel Mar'gln="10j 10 , 10 , 10 "> 

<RadioButton Name="rdbtnOriginalFamily" 

IsChecked="True" 

Click="FontChanged">Original</RadioButton> 

<RadioButton Name="rdbtnTimes" 

Click="FontChanged">Times New Roman</RadioButton> 

<RadioButton Name="rdbtnWingdings" 

Click="FontChanged">Wingdings</RadioButton> 

</StackPanel> 

<TextBlock Style="{StaticResour'ce titleText}">Font Size</TextBlock> 

<StackPanel Har'gin="10j 10 , 10 , 10 "> 

<RadioButton Name="rdbtnOriginalSize" 

IsChecked="Tr'ue" 

Click="FontSizeChanged">Original</RadioButton> 

<RadioButton Name="rdbtnTen" 

Cllck="FontSizeChanged">10</RadioButton> 

<RadioButton Name="rdbtnTwelve" 

Click="FontSizeChanged">12</RadioButton> 

</StackPanel> 

<TextBlock Style="{StaticResour'ce titleText}">Font Style</TextBlock> 

<StackPanel Har'gin="10j 10 , 10 , 10 "> 

<RadioButton Name="rdbtnNormalStyle" 

IsChecked="True" 

Click="StyleChanged">Original</RadioButton> 

<RadioButton Name="rdbtnltalic" 

Clicks"StyleChanged">Italic</RadioButton> 

</StackPanel> 

<TextBlock Style="{StaticResour'ce titleText}">Font Weight</TextBlock> 
<StackPanel Har'gin="10j 10,10,10" > 

<RadioButton Name="rdbtnOriginalWeight" 

IsChecked="True" 

Click="WeightChanged"> 

Original 

</RadioButton> 

<RadioButton Name="rdbtnBold" 

Click="WeightChanged">Bold</RadioButton> 

</StackPanel> 

</StackPanel> 

<WindowsFormsFlost Name="wfh" 

DockPanel.Dock="Top" 

Height="300"> 

<mcl:MyControll Name="mc"/> 

</WindowsFormsFlost> 

<StackPanel Orientation="Vertical" 

Helght="Auto" 

Background="LightBlue"> 

<TextBlock Margin="10,10,10,10" 

FontWeight="Bold" 

FontSize="12">Data From Control</TextBlock> 

<TextBlock Style="{StaticResource titleText}"> 

Name: <Span Name="txtName" Style="{StaticResource inlineText}"/> 

</TextBlock> 

<TextBlock Style="{StaticResource titleText}"> 

Street Address: <Span Name="txtAddress" Style="{StaticResource inlineText}"/> 
</TextBlock> 

<TextBlock Style="{StaticResource titleText}"> 


City: <Span Mame="txtCity" Style="{StaticResource inlineText}"/> 
</TextBlock> 

<TextBlock Style="{StaticResour'ce titleText}"> 

State: <Span Name="txtState" Style="{StaticResource inlineText}"/> 
</TextBlock> 

<TextBlock Style="{StaticResour'ce titleText}"> 

Zip: <Span Name="txtZip" Style="{StaticResource inlineText}"/> 
</TextBlock> 

</StackPanel> 

</DockPanel> 

</Window> 


The first StackPanel element contains several sets of RadioButton controls that enable you to modify various 
default properties of the hosted control. That is followed by a WindowsFormsHost element, which hosts 
MyControii . The final StackPanel element contains several TextBlock elements that display the data that is 
returned by the hosted control. The ordering of the elements and the Dock and Height attribute settings embed 
the hosted control into the window with no gaps or distortion. 

Hosting the Control 

The following edited version of the previous XAML focuses on the elements that are needed to host MyControii . 

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/pnesentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

X:Class="WpfHost.MainWindow" 

xmlns:mcl="clr-namespace:MyControlsjassembly=MyControls" 

Loaded="Init"> 


<WindowsFormsHost Name="wfh" 

DockPanel.Dock="Top" 

Height="300"> 

<mcl:MyControll Name="mc"/> 

</WindowsFormsHost> 

The xmlns namespace mapping attribute creates a reference to the MyControis namespace that contains the 

hosted control. This mapping enables you to represent MyControii in XAML as <mci:MyControii> . 

Two elements in the XAML handle the hosting: 

• WindowsFormsHost represents the WindowsFormsHost element that enables you to host a Windows Forms 
control in a WPF application. 

• mci:MyControii , which represents MyControii , is added to the WindowsFormsHost element's child 
collection. As a result, this Windows Forms control is rendered as part of the WPF window, and you can 
communicate with the control from the application. 

Implementing the Code-Behind File 

The code-behind file, MainWindow.xaml.vb or MainWindow.xaml.cs, contains the procedural code that 

implements the functionality of the Ul discussed in the preceding section. The primary tasks are: 

• Attaching an event handler to MyControii 's onButtonciick event. 

• Modifying various properties of MyControii , based on how the collection of option buttons are set. 

• Displaying the data collected by the control. 

Initializing the Application 

The initialization code is contained in an event handler for the window's Loaded event and attaches an event 

handler to the control's onButtonciick event. 













In MainWindow.xaml.vb or MainWindow.xannl.es, add the following code to the MainWindow class. 

private Application app; 
private Window myWindow; 

FontWeight initFontWeight; 

Double initFontSize; 

FontStyle initFontStyle; 

SolidColorBrush initBackBrush; 

SolidColorBrush initForeBrush; 

FontFamily initFontFamily; 
bool UIIsReady = false; 

private void Init(object sender, EventArgs e) 

{ 

app = System.Windows.Application.Current; 
myWindow = (Window)app.MainWindow; 

myWindow.SizeToContent = SizeToContent.WidtbAndHeight; 

wfh.TabIndex = 10; 

initFontSize = wfh.FontSize; 

initFontWeight = wfb.FontWeight; 

initFontFamily = wfb.FontFamily; 

initFontStyle = wfb.FontStyle; 

initBackBrush = (SolidColorBrush)wfh.Background; 

initForeBrush = (SolidColorBrush)wfh.Foreground; 

(wfb.Child as MyControll).OnButtonClick += new MyControll.MyControlEventHandler(Panel_OnButtonClick); 
UIIsReady = true; 

} 


Private app As Application 
Private myWindow As Window 
Private initFontWeight As FontWeight 
Private initFontSize As [Double] 

Private initFontStyle As FontStyle 
Private initBackBrush As SolidColorBrush 
Private initForeBrush As SolidColorBrush 
Private initFontFamily As FontFamily 
Private UIIsReady As Boolean = False 

Private Sub Init(By\/al sender As Object, ByVal e As RoutedEventArgs) 
app = System.Windows.Application.Current 
myWindow = CType(app.MainWindow, Window) 
myWindow.SizeToContent = SizeToContent.WidthAndHeight 
wfh.TabIndex = 10 
initFontSize = wfh.FontSize 
initFontWeight = wfh.FontWeight 
initFontFamily = wfh.FontFamily 
initFontStyle = wfh.FontStyle 

initBackBrush = CType(wfh.Background, SolidColorBrush) 
initForeBrush = CType(wfh.Foreground, SolidColorBrush) 

Dim me As MyControll = wfh.Child 

AddHandler me.OnButtonClick, AddressOf Panel_OnButtonClick 
UIIsReady = True 

End Sub 

Because the XAML discussed previously added MyControll to the WindowsFormsHost element's child element 
collection, you can cast the WindowsFormsHost element's Child to get the reference to MyControll . You can then 
use that reference to attach an event handler to OnButtonClick . 


In addition to providing a reference to the control itself, WindowsFormsHost exposes a number of the control's 










properties, which you can manipulate from the application. The initialization code assigns those values to private 
global variables for later use in the application. 

So that you can easily access the types in the MyControis DLL, add the following imports or using statement to 
the top of the file. 

Imports MyControis 


using MyControis; 

Handling the OnButtonClick Event 



//Handle button clicks on the Windows Form control 

private void Panel_OnButtonClick(object sender, MyControlEventArgs args) 

{ 

txtName.Inlines.ClearO; 
txtAddress.Inlines.Clear(); 
txtCity.Inlines.ClearO; 
txtState.Inlines.Clear(); 
txtZip.Inlines.Clear(); 

if (args.IsOK) 

{ 

txtName.Inlines.Add( " " + args.MyName ); 
txtAddress.Inlines.Add( " " + args.MyStreetAddress ); 
txtCity.Inlines.Add( " " + args.MyCity ); 
txtState.Inlines.Add( " " + args.MyState ); 
txtZip.Inlines.Add( " " + args.MyZip ); 

} 

} 


'Handle button clicks on the Windows Form control 

Private Sub Panel_OnButtonClick(ByVal sender As Object, ByVal args As MyControlEventArgs) 
txtName.Inlines.Clear() 
txtAddress.Inlines.Clear() 
txtCity.Inlines.ClearO 
txtState.Inlines.Clear() 
txtZip.Inlines.Clear() 

If args.IsOK Then 

txtName.Inlines.Add(" " + args.MyName) 
txtAddress.Inlines.Add(" " + args.MyStreetAddress) 
txtCity.Inlines.Add(" " + args.MyCity) 
txtState.Inlines.Add(" " + args.MyState) 
txtZip.Inlines.Add(" " + args.MyZip) 

End If 

End Sub 

The data in the text boxes is packed into the MyControlEventArgs object. If the user clicks the OK button, the event 
handler extracts the data and displays it in the panel below MyControii . 

Modifying the Control's Properties 

The WindowsFormsHost element exposes several of the hosted control's default properties. As a result, you can 
change the appearance of the control to match the style of your application more closely. The sets of option 
buttons in the left panel enable the user to modify several color and font properties. Each set of buttons has a 














handler for the Click event, which detects the user's option button selections and changes the corresponding 
property on the control. 

Add the following code to the MainWindow class. 

private void BackColorChanged(object sendeCj RoutedEventArgs e) 

{ 

if (sender == rdbtnBackGreen) 

wfh.Background = new SolidColorBrush(Colors.LightGreen)j 
else if (sender == rdbtnBackSalmon) 

wfh.Background = new SolidColorBrush(Colors.LightSalmon); 
else if (UIIsReady == true) 

wfh.Background = initBackBrush; 


private void ForeColorChanged(object sender^ RoutedEventArgs e) 

{ 

if (sender == rdbtnForeRed) 

wfh.Foreground = new SolidColorBrush(Colors.Red); 
else if (sender == rdbtnForeYellow) 

wfh.Foreground = new SolidColorBrush(Colors.Yellow); 
else if (UIIsReady == true) 

wfh.Foreground = initForeBrush; 

} 

private void FontChanged(object sender^ RoutedEventArgs e) 

{ 

if (sender == rdbtnlimes) 

wfh.FontFamily = new FontFamily("Times New Roman"); 
else if (sender == rdbtnWingdings) 

wfh.FontFamily = new FontFamilyC'Wingdings"); 
else if (UIIsReady == true) 

wfh.FontFamily = initFontFamily; 

} 

private void FontSizeChanged(object sender, RoutedEventArgs e) 

{ 

if (sender == rdbtnTen) 
wfh.FontSize = 10; 
else if (sender == rdbtnlwelve) 
wfh.FontSize = 12; 
else if (UIIsReady == true) 

wfh.FontSize = initFontSize; 

} 

private void StyleChanged(object sender, RoutedEventArgs e) 

{ 

if (sender == rdbtnitalic) 

wfh.FontStyle = FontStyles.Italic; 
else if (UIIsReady == true) 

wfh.FontStyle = initFontStyle; 

} 

private void WeightChanged(object sender, RoutedEventArgs e) 

{ 

if (sender == rdbtnBold) 

wfh.FontWeight = FontWeights.Bold; 
else if (UIIsReady == true) 

wfh.FontWeight = initFontWeight; 




Private Sub BackColorChanged(By\/al sender As Object^ ByVal e As RoutedEventArgs) 

If sender.Equals(rdbtnBackGreen) Then 

wfh.Background = New SolidColorBrush(Colors.LightGreen) 

Elself sender.Equals(rdbtnBackSalmon) Then 

wfh.Background = New SolidColorBrush(Colors.LightSalmon) 

Elself UIIsReady = True Then 

wfh.Background = initBackBrush 
End If 

End Sub 

Private Sub ForeColorChanged(By\/al sender As Object^ ByVal e As RoutedEventArgs) 
If sender.Equals(rdbtnForeRed) Then 

wfh.Foreground = New SolidColorBrush(Colors.Red) 

Elself sender.Equals(rdbtnForeYellow) Then 

wfh.Foreground = New SolidColorBrush(Colors.Yellow) 

Elself UIIsReady = True Then 

wfh.Foreground = initForeBrush 
End If 

End Sub 

Private Sub FontChanged(ByVal sender As Object, ByVal e As RoutedEventArgs) 

If sender.Equals(rdbtnTimes) Then 

wfh.FontFamily = New FontFamily("Times New Roman") 

Elself sender.Equals(rdbtnWingdings) Then 

wfh.FontFamily = New FontFamilyC'Wingdings") 

Elself UIIsReady = True Then 

wfh.FontFamily = initFontFamily 
End If 

End Sub 

Private Sub FontSizeChanged(ByVal sender As Object, ByVal e As RoutedEventArgs) 
If sender.Equals(rdbtnTen) Then 
wfh.FontSize = 10 

Elself sender.Equals(rdbtnTwelve) Then 
wfh.FontSize = 12 
Elself UIIsReady = True Then 
wfh.FontSize = initFontSize 
End If 

End Sub 

Private Sub StyleChanged(ByVal sender As Object, ByVal e As RoutedEventArgs) 

If sender.Equals(rdbtnltalic) Then 
wfh.FontStyle = FontStyles.Italic 
Elself UIIsReady = True Then 

wfh.FontStyle = initFontStyle 
End If 

End Sub 

Private Sub WeightChanged(ByVal sender As Object, ByVal e As RoutedEventArgs) 

If sender.Equals(rdbtnBold) Then 

wfh.FontWeight = FontWeights.Bold 
Elself UIIsReady = True Then 

wfh.FontWeight = initFontWeight 
End If 

End Sub 


Build and run the application. Add some text in the Windows Forms composite control and then click OK. The text 
appears in the labels. Click the different radio buttons to see the effect on the control. 



See also 
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Walkthrough: Hosting an ActiveX Control in WPF 

1/28/2020 « 3 minutes to read • Edit Online 


To enable improved interaction with browsers, you can use Microsoft ActiveX controls in your WPF-based 
application. This walkthrough demonstrates how you can host the Microsoft Windows Media Player as a control on 
a WPF page. 

Tasks illustrated in this walkthrough include: 

• Creating the project. 

• Creating the ActiveX control. 

• Hosting the ActiveX control on a WPF Page. 

When you have completed this walkthrough, you will understand how to use Microsoft ActiveX controls in your 
WPF-based application. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Microsoft Windows Media Player installed on the computer where Visual Studio is installed. 

• Visual Studio 2010. 

Creating the Project 

To create and set up the project 

1. Create a WPF Application project named HostingAxinWpf . 

2. Add a Windows Forms Control Library project to the solution, and name the project wmpAxiib . 

3. In the WmpAxLib project, add a reference to the Windows Media Player assembly, which is named wmp.dll. 

4. Open the Toolbox. 

5. Right-click in the Toolbox, and then click Choose Items. 

6. Click the COM Components tab, select the Windows Media Player control, and then click OK. 

The Windows Media Player control is added to the Toolbox. 

7. In Solution Explorer, right-click the UserControl 1 file, and then click Rename. 

8. Change the name to wmpAxControi.vb or wmpAxControi.cs , depending on the language. 

9. If you are prompted to rename all references, click Yes. 

Creating the ActiveX Control 

Visual Studio automatically generates an AxHost wrapper class for a Microsoft ActiveX control when the control is 
added to a design surface. The following procedure creates a managed assembly named Axlnterop.WMPLib.dll. 

To create the ActiveX control 

1. Open WmpAxControi.vb or WmpAxControl.es in the Windows Forms Designer. 








2. From the Toolbox, add the Windows Media Player control to the design surface. 

3. In the Properties window, set the value of the Windows Media Player control's Dock property to Fill. 

4. Build the WmpAxLib control library project. 

Hosting the ActiveX Control on a WPF Page 

To host the ActiveX control 

1. In the HostingAxInWpf project, add a reference to the generated ActiveX interoperability assembly. 

This assembly is named Axlnterop.WMPLib.dll and was added to the Debug folder of the WmpAxLib project 
when you imported the Windows Media Player control. 

2. Add a reference to the WindowsFormsIntegration assembly, which is named WindowsFormslntegration.dll. 

3. Add a reference to the Windows Forms assembly, which is named System.Windows.Forms.dll. 

4. Open MainWindow.xamI in the WPF Designer. 

5. Name the Grid element gnidi . 

<Grid Name="gr'idl"> 

</Gr'id> 


6. In Design view or XAML view, select the Window element. 

7. In the Properties window, click the Events tab. 

8. Double-click the Loaded event. 

9. Insert the following code to handle the Loaded event. 

This code creates an instance of the WindowsFormsHost control and adds an instance of the 
AxWindowsMediaPlayen control aS its child. 

private void Window_Loaded(object sendetj RoutedEventArgs e) 

{ 

// Create the interop host control. 

System.Windows.Forms.Integration.WindowsFormsHost host = 

new System.Windows.Forms.Integration.WindowsFormsHost(); 

// Create the ActiveX control. 

WmpAxLih.AxWindowsMediaPlayer axWmp = new WmpAxLih.AxWindowsMediaPlayer(); 

// Assign the ActiveX control as the host control's child, 
host.Child = axWmp; 

// Add the interop host control to the Grid 
// control's collection of child controls, 
this.gridl.Children.Add(host); 

// Play a .wav file with the ActiveX control. 
axWmp.URL = @"C:\Windows\Media\tada.wav"; 




Private Sub Window_Loaded(By\/al sender As Object^ ByVal e As RoutedEventArgs) 
' Create the interop host control. 

Dim host As New System.Windows.Forms.Integration.WindowsFormsHost() 

' Create the ActiveX control. 

Dim axWmp As New AxWMPLib.AxWindowsMediaPlayer() 

' Assign the ActiveX control as the host control's child, 
host.Child = axWmp 

' Add the interop host control to the Grid 
' control's collection of child controls. 

Me.gridl.Children.Add(host) 

' Play a .wav file with the ActiveX control. 
axWmp.URL = "C:\Windows\Media\tada.wav" 

End Sub 


10. Press F5 to build and run the application. 

See also 

• ElementHost 

• WindowsFormsHost 

• Design XAML in Visual Studio 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 



How to: Enable Visual Styles in a Hybrid Application 

1/28/2020 « 2 minutes to read • Edit Online 


This topic shows how to enable visual styles on a Windows Forms control hosted in a WPF-based application. 

If your application calls the EnableVisualStyles method, most of your Windows Forms controls will automatically 
use visual styles. For more information, see Rendering Controls with Visual Styles. 

For a complete code listing of the tasks illustrated in this topic, see Enabling Visual Styles in a Hybrid Application 
Sample. 

Enabling Windows Forms Visual Styles 

To enable Windows Forms visual styles 

1. Create a WPF Application project named HostingWfWithVisuaistyies . 

2. In Solution Explorer, add references to the following assemblies. 

• WindowsFormsIntegration 

• System.Windows.Forms 

3. In the Toolbox, double-click the Grid icon to place a Grid element on the design surface. 

4. In the Properties window, set the values of the Height and Width properties to Auto. 

5. In Design view or XAML view, select the Window. 

6. In the Properties window, click the Events tab. 

7. Double-click the Loaded event. 

8. In MainWindow.xaml.vb or MainWindow.xaml.es, insert the following code to handle the Loaded event. 

private void Window_Loaded(object sendetj RoutedEventArgs e) 

{ 

// Comment out the following line to disable visual 
// styles for the hosted Windows Forms control. 

System.Windows.Forms.Application.EnableVisualStyles(); 

// Create a WindowsFormsHost element to host 
// the Windows Forms control. 

System.Windows.Forms.Integration.WindowsFormsHost host = 

new System.Windows.Forms.Integration.WindowsFormsHost(); 

// Create a Windows Forms tab control. 

System.Windows.Forms.TabControl tc = new System.Windows.Forms.TabControl()j 

tc.TabPages.Add("Tabl"); 

tc.TabPages.Add("Tab2"); 

// Assign the Windows Forms tab control as the hosted control, 
host.Child = tc; 

// Assign the host element to the parent Grid element, 
this.gridl.Children.Add(host); 

} 






Private Sub Window_Loaded(By\/al sender As Object^ ByVal e As RoutedEventArgs) 
' Comment out the following line to disable visual 
' styles for the hosted Windows Forms control. 

System.Windows.Forms.Application.EnableVisualStyles() 

' Create a WindowsFormsHost element to host 
' the Windows Forms control. 

Dim host As New System.Windows.Forms.Integration.WindowsFormsHost() 

' Create a Windows Forms tab control. 

Dim tc As New System.Windows.Forms.TabControl() 

tc.TabPages.Add("Tabl") 

tc.TabPages.Add("Tab2") 

' Assign the Windows Forms tab control as the hosted control, 
host.Child = tc 

' Assign the host element to the parent Grid element. 

Me.gridl.Children.Add(host) 

End Sub 


9. Press F5 to build and run the application. 

The Windows Fornns control is painted with visual styles. 

Disabling Windows Forms Visual Styles 

To disable visual styles, simply remove the call to the EnableVisualStyles method. 

To disable Windows Forms visual styles 

1. Open MainWindow.xaml.vb or MainWindow.xaml.es in the Code Editor. 

2. Comment out the call to the EnableVisualStyles method. 

3. Press F5 to build and run the application. 

The Windows Forms control is painted with the default system style. 

See also 

• EnableVisualStyles 

• System.Windows.Forms.VisualStyles 

• WindowsFormsHost 

• Rendering Controls with Visual Styles 

• Walkthrough: Hosting a Windows Forms Control in WPF 



Walkthrough: Arranging Windows Forms Controls in 
WPF 

2/8/2020 • 9 minutes to read i Edit Online 


This walkthrough shows you how to use WPF layout features to arrange Windows Forms controls in a hybrid 
application. 

Tasks illustrated in this walkthrough include: 

• Creating the project. 

• Using default layout settings. 

• Sizing to content. 

• Using absolute positioning. 

• Specifying size explicitly. 

• Setting layout properties. 

• Understanding z-order limitations. 

• Docking. 

• Setting visibility. 

• Hosting a control that does not stretch. 

• Scaling. 

• Rotating. 

• Setting padding and margins. 

• Using dynamic layout containers. 

For a complete code listing of the tasks illustrated in this walkthrough, see Arranging Windows Forms Controls 
WPF Sample. 

When you are finished, you will have an understanding of Windows Forms layout features in WPF-based 
applications. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Creating the Project 

To create and set up the project, follow these steps: 

1. Create a WPF Application project named wpfiayoutHostingWf . 

2. In Solution Explorer, add references to the following assemblies: 

• WindowsFormsIntegration 

• System.Windows.Forms 

• System.Drawing 

3. Double-click MainWindow.xamIXo open it in XAML view. 

4. In the Window element, add the following Windows Forms namespace mapping. 





xmlns :wf="clr-namespace:System.Windows.Formsjassembly=System.Windows.Forms" 

5. In the Grid element set the ShowGridLines property to true and define five rows and three columns. 

<Grid ShowGridLines="true"> 

<Grid.RowDefinitions> 

<RowDefinition/> 

<RowDefinition/> 

<RowDefinition/> 

<RowDefinition/> 

<RowDefinition/> 

</Grid.RowDefinitions> 

<Grid.ColumnDefinitions> 

<ColumnDefinition/> 

<ColumnDefinition/> 

<ColumnDefinition/> 

</Grid.ColumnDefinitions> 


Using Default Layout Settings 

By default, the WindowsFormsHost element handles the layout for the hosted Windows Forms control. 
To use default layout settings, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Default layout. --> 

<Canvas Grid.Row="0" Grid.Column="0"> 

<WindowsFormsHost Bacl<ground="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

</Canvas> 


2. Press F5 to build and run the application. The Windows Forms System.Windows.Forms.Button control 
appears in the Canvas. The hosted control is sized based on its content, and the WindowsFormsHost 
element is sized to accommodate the hosted control. 

Sizing to Content 

The WindowsFormsHost element ensures that the hosted control is sized to display its content properly. 
To size to content, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Sizing to content. --> 

<Canvas Grid.Row="l" Grid.Column="0"> 

<WindowsFormsHost Bacl<ground="Orange"> 

<wf:Button Text="Windows Forms control with more content" FlatStyle="Flat"/> 

</WindowsFormsHost> 

</Canvas> 

<Canvas Grid.Row="2" Grid.Column="0"> 

<WindowsFormsHost FontSize="24" Bacl<ground="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

</Canvas> 







2. Press F5 to build and run the application. The two new button controls are sized to display the longer text 
string and larger font size properly, and the WindowsFormsHost elements are resized to accommodate the 
hosted controls. 

Using Absolute Positioning 

You can use absolute positioning to place the WindowsFormsHost element anywhere in the user interface (Ul). 
To use absolute positioning, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Absolute positioning. --> 

<Canvas Gnid.Row="3" Grid.Column="0"> 

<WindowsFormsHost Canvas.Top="20" Canvas.Left="20" Background="Yellow"> 

<wf:Button Text="Windows Forms control with absolute positioning" FlatStyle="Flat"/> 

</WindowsFormsHost) 

</Canvas> 


2. Press F5 to build and run the application. The WindowsFormsHost element is placed 20 pixels from the top 
side of the grid cell and 20 pixels from the left. 

Specifying Size Explicitly 

You can specify the size of the WindowsFormsHost element using the Width and Height properties. 

To specify size explicitly, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Explicit sizing. --> 

<Canvas Grid.Row="4" Grid.Column="0"> 

<WindowsFormsHost Width="50" Height="70" Background="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost) 

</Canvas) 


2. Press F5 to build and run the application. The WindowsFormsHost element is set to a size of 50 pixels wide 
by 70 pixels high, which is smaller than the default layout settings. The content of the Windows Forms 
control is rearranged accordingly. 

Setting Layout Properties 

Always set layout-related properties on the hosted control by using the properties of the WindowsFormsHost 
element. Setting layout properties directly on the hosted control will yield unintended results. 

Setting layout-related properties on the hosted control in XAML has no effect. 

To see the effects of setting properties on the hosted control, follow these steps: 


1. Copy the following XAML into the Grid element: 




<!-- Setting hosted control properties directly. --> 

<Canvas Grid.Row="0" Grid.Column="l"> 

<WindowsFormsHost Width="160" Height="50" Background="Yellow"> 

<wf:Button Name="buttonl" Click="buttonl_Click" Text="Click me" FlatStyle="Flat" BackColor="Green"/> 
</WindowsFormsHost> 

</Canvas> 


2. In Solution Explorer, double-click MainWindow.xaml.vbor MainWindow.xaml.esto open it in the Code 
Editor. 

3. Copy the following code into the MainWindow class definition: 

private void buttonl_Click(object sender^ EventArgs e ) 

{ 

System.Windows.Forms.Button b = sender as System.Windows.Forms.Button; 

b.Top = 20; 
b.Left = 20; 


Private Sub buttonl_Click(By\/al sender As Object^ ByVal e As EventArgs) 
Dim b As System.Windows.Forms.Button = sender 

b.Top = 20 
b.Left = 20 

End Sub 


4. Press F5 to build and run the application. 

5. Click the Click me button. The buttoni_ciick event handler sets the Top and Left properties on the hosted 
control. This causes the hosted control to be repositioned within the WindowsFormsHost element. The host 
maintains the same screen area, but the hosted control is clipped. Instead, the hosted control should always 
fill the WindowsFormsHost element. 

Understanding Z-Order Limitations 

Visible WindowsFormsHost elements are always drawn on top of other WPF elements, and they are unaffected by 
z-order. To see this z-order behavior, do the following: 

1. Copy the following XAML into the Grid element: 

<!-- Z-order demonstration. --> 

<Canvas Grid.Row="l" Grid.Column="l"> 

<WindowsFormsHost Canvas.Top="20" Canvas.Left="20" Background="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

<Label Content="A WPF label" FontSize="24"/> 

</Canvas> 


2. Press F5 to build and run the application. The WindowsFormsHost element is painted over the label 
element. 

Docking 

WindowsFormsHost element supports WPF docking. Set the Dock attached property to dock the hosted control in 
a DockPanel element. 







To dock a hosted control, follow these steps: 

1. Copy the following XAML into the Grid elennent: 


<!-- Docking a WindowsFormsHost element. --> 

<DockPanel LastChildFill="false" Gnid.Row="2" Grid.Column="l"> 

<WindowsFormsHost DockPanel.Dock="Right" Canvas.Top="20" Canvas.Left="20" Background="Yellow"> 
<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

</DockPanel> 


2. Press F5 to build and run the application. The WindowsFormsHost element is docked to the right side of the 
DockPanel element. 

Setting Visibility 

You can make your Windows Forms control invisible or collapse it by setting the Visibility property on the 
WindowsFormsHost element. When a control is invisible, it is not displayed, but it occupies layout space. When a 
control is collapsed, it is not displayed, nor does it occupy layout space. 

To set the visibility of a hosted control, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Setting Visibility to hidden and collapsed. --> 

<StackPanel Grid.Row="3" Grid.Column="l"> 

<Button Name="button2" Cllck="button2_Click" Content="Click to make invisible" 

Background="OrangeRed"/> 

<WindowsFormsHost Name="hostl" Background="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

<Button Name="button3" Click="button3_Click" Content="Click to collapse" Background="OrangeRed"/> 
</StackPanel> 


2. In MainWindow.xaml.vb or MainWindow.xaml.es, copy the following code into the class definition: 

private void button2_Click(object sender^ EventArgs e) 

{ 

this.hostl.Visibility = Visibility.Hidden; 

} 

private void button3_Click(object sender^ EventArgs e) 

{ 

this.hostl.Visibility = Visibility.Collapsed; 

} 


Private Sub button2_Click(ByVal sender As Objectj ByVal e As RoutedEventArgs) 
Me.hostl.Visibility = Windows.Visibility.Hidden 
End Sub 


Private Sub button3_Click(ByVal sender As Objectj ByVal e As RoutedEventArgs) 
Me.hostl.Visibility = Windows.Visibility.Collapsed 
End Sub 


3. Press F5 to build and run the application. 

4. Click the Click to make invisible button to make the WindowsFormsHost element invisible. 





5. Click the Click to collapse button to hide the WindowsFormsHost element from the layout entirely. When 
the Windows Forms control is collapsed, the surrounding elements are rearranged to occupy its space. 

Hosting a Control That Does Not Stretch 

Some Windows Forms controls have a fixed size and do not stretch to fill available space in the layout. For example, 
the MonthCalendar control displays a month in a fixed space. 

To host a control that does not stretch, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Hosting a control that does not stretch. --> 

<!-- The MonthCalendar has a discrete size. --> 
cStackPanel Grid.Row="4" Grid.Column="l"> 

<Label Content="A WPF element" Background="OrangeRed"/> 

<WindowsFormsHost Background="Yellow"> 

<wf:MonthCalendar/> 

</WindowsFormsHost> 

<Label Content="Another WPF element" Background="OrangeRed"/> 

</StackPanel> 


2. Press F5 to build and run the application. The WindowsFormsHost element is centered in the grid row, but it 
is not stretched to fill the available space. If the window is large enough, you may see two or more months 
displayed by the hosted MonthCalendar control, but these are centered in the row. The WPF layout engine 
centers elements that cannot be sized to fill the available space. 

Scaling 

Unlike WPF elements, most Windows Forms controls are not continuously scalable. To provide custom scaling, you 
override the WindowsFormsHost.ScaleChild method. 

To scale a hosted control by using the default behavior, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Scaling transformation. --> 

<StackPanel Grid.Row="0" Grid.Column="2"> 

<StackPanel.RenderTransform> 

<ScaleTransform CenterX="0" CenterY="0" ScaleX="0.5" ScaleY="0.5" /> 

</StackPanel.RenderTransform> 

<Label Content="A WPF UIElement" Background="OrangeRed"/> 

<WindowsFormsHost Background="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost) 

<Label Content="Another WPF UIElement" Background="OrangeRed"/> 

</StackPanel> 


2. Press F5 to build and run the application. The hosted control and its surrounding elements are scaled by a 
factor of 0.5. However, the hosted control's font is not scaled. 

Rotating 

Unlike WPF elements, Windows Forms controls do not support rotation. The WindowsFormsHost element does not 




rotate with other WPF elements when a rotation transformation is applied. Any rotation value other than 180 
degrees raises the LayoutError event. 

To see the effect of rotation in a hybrid application, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Rotation transformation. --> 

<StackPanel Grid.Row="l" Grid.Column="2"> 

<StackPanel.RenderTransform> 

<RotateTransform CenterX="200" CenterY="50" Angle="180" /> 

</StackPanel.RenderTransform> 

<Label Content="A WPF element" Background="OrangeRed"/> 

<WindowsFormsHost Background="Yellow"> 

<wf:Button Text="Windows Forms control" FlatStyle="Flat"/> 

</WindowsFormsHost> 

<Label Content="Another WPF element" Background="OrangeRed"/> 

</StackPanel> 


2. Press F5 to build and run the application. The hosted control is not rotated, but its surrounding elements are 
rotated by an angle of 180 degrees. You may have to resize the window to see the elements. 

Setting Padding and Margins 

Padding and margins in WPF layout are similar to padding and margins in Windows Forms. Simply set the Padding 
and Margin properties on the WindowsFormsHost element. 

To set padding and margins for a hosted control, follow these steps: 

1. Copy the following XAML into the Grid element: 

<!-- Padding. --> 

<Canvas Grid.Row="2" Grid.Column="2"> 

<WindowsFormsFlost Padding="0, 20^ 0j 0" Background="Yellow"> 

<wf:Button Text="Windows Forms control with padding" FlatStyle="Flat"/> 

</WindowsFormsHost> 

</Canvas> 


<!-- Margin. --> 

<Canvas Grid.Row="3" Grid.Column="2"> 

<WindowsFormsFlost Margin="20j 20^ 0j 0" Background="Yellow"> 

<wf:Button Text="Windows Forms control with margin" FlatStyle="Flat"/> 
</WindowsFormsHost> 

</Canvas> 


2. Press F5 to build and run the application. The padding and margin settings are applied to the hosted 
Windows Forms controls in the same way they would be applied in Windows Forms. 

Using Dynamic Layout Containers 

Windows Forms provides two dynamic layout containers, FlowLayoutPanel and TableLayoutPanel. You can also use 
these containers in WPF layouts. 


To use a dynamic layout container, follow these steps: 




1. Copy the following XAML into the Grid elennent: 


<!-- Flow layout. --> 

<DockPanel Grid.Row="4" Grid.Column="2"> 

<WindowsFormsHost Name="flowLayoutHost" Background="Yellow"> 
<wf:FlowLayoutPanel/> 

</WindowsFormsHost> 

</DockPanel> 


2. In MainWindow.xaml.vb or MainWindow.xaml.cs, copy the following code into the class definition 

private void InitializeFlowLayoutPanel() 

{ 

System.Windows.Forms.FlowLayoutPanel flp = 

this.flowLayoutHost.Child as System.Windows.Forms.FlowLayoutPanel; 

flp.WrapContents = true; 

const int numButtons = 6; 

for (int i = 0; i < numButtons; i++) 

{ 

System.Windows.Forms.Button b = new System.Windows.Forms.Button(); 
b.Text = "Button"; 

b.BackColor = System.Drawing.Color.AliceBlue; 
b.FlatStyle = System.Windows.Forms.FlatStyle.Flat; 

fIp.Controls.Add(b); 

} 

} 


Private Sub InitializeFlowLayoutPanel() 

Dim flp As System.Windows.Forms.FlowLayoutPanel = Me.flowLayoutHost.Child 

flp.WrapContents = True 

Const numButtons As Integer = 6 

Dim i As Integer 

For i = 0 To numButtons 

Dim b As New System.Windows.Forms.Button() 
b.Text = "Button" 

b.BackColor = System.Drawing.Color.AliceBlue 
b.FlatStyle = System.Windows.Forms.FlatStyle.Flat 

fIp.Controls.Add(b) 

Next i 

End Sub 


3. Add a call to the initiaiizeFiowLayoutPanei method in the constructor: 


public MainWindowO 

{ 

InitializeComponent(); 

this. InitializeFlowLayoutPanelO; 

} 





Public Sub New() 

InitializeComponent() 

Me.InitlalizeFlowLayoutPanelO 

End Sub 

4. Press F5 to build and run the application. The WindowsFormsHost elennent fills the DockPanel, and 
FlowLayoutPanel arranges its child controls in the default FlowDirection. 

See also 

• ElementHost 

• WindowsFormsHost 

• Design XAML in Visual Studio 

• Layout Considerations for the WindowsFormsHost Element 

• Arranging Windows Forms Controls in WPF Sample 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 



Walkthrough: Binding to Data in Hybrid Applications 

2/8/2020 • 6 minutes to read ^ Edit Online 


Binding a data source to a control is essential for providing users with access to underlying data, whether you are 
using Windows Forms or WPF. This walkthrough shows how you can use data binding in hybrid applications that 
include both Windows Forms and WPF controls. 

Tasks illustrated in this walkthrough include: 

• Creating the project. 

• Defining the data template. 

• Specifying the form layout. 

• Specifying data bindings. 

• Displaying data by using interoperation. 

• Adding the data source to the project. 

• Binding to the data source. 

For a complete code listing of the tasks illustrated in this walkthrough, see Data Binding in Hybrid Applications 
Sample. 

When you are finished, you will have an understanding of data binding features in hybrid applications. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio. 

• Access to the Northwind sample database running on Microsoft SQL Server. 

Creating the Project 

To create and set up the project 

1. Create a WPF Application project named wPFWithWFAndDatabinding . 

2. In Solution Explorer, add references to the following assemblies. 

• WindowsFormsIntegration 

• System.Windows.Forms 

3. Open MainWindow.xamI in the WPF Designer. 

4. In the Window element, add the following Windows Forms namespaces mapping. 

xmlns:wf="clr-namespace:System.Windows.Forms;assembly=System.Windows.Forms" 


5. Name the default Grid element mainCrid by assigning the Name property. 






<Grid x:Name="mainGr'id"> 


Defining the Data Template 

The master list of customers is displayed in a ListBox control. The following code example defines a DataTemplate 
object named listitemsTempiate that controls the visual tree of the ListBox control. This DataTemplate is assigned 
to the ListBox control's ItemTemplate property. 

To define the data template 

• Copy the following XAML into the Grid element's declaration. 

<Grid.Resouncesx 

<DataTemplate x:Key="ListItemsTemplate"> 

<TextBlock Text="{Binding Path=ContactName}"/> 

</DataTemplate> 

</Gr'id. Resources> 


Specifying the Form Layout 

The layout of the form is defined by a grid with three rows and three columns. Label controls are provided to 

identify each column in the Customers table. 

To set up the Grid layout 

• Copy the following XAML into the Grid element's declaration. 

<Grid.RowDefinitions> 

<RowDefinltion Height="Auto"/> 

<RowDefinltion Helght="Auto"/> 

<RowDefinition Height="Auto"/> 

</Gr'id.RowDefinitions> 

<Grid.ColumnDefinltions> 

<ColumnDefinition Width="Auto"/> 

<ColumnDefinition Width="Auto"/> 

<ColumnDefinition Width="Auto"/> 

</Grid.ColumnDefinitions> 


To set up the Label controls 

• Copy the following XAML into the Grid element's declaration. 

<Stacl<Panel Orientation="Ventical" Grid.Row="0" Grid.Column="l"> 
<Label Margin="20j38,5,2">First Name:</Label> 

<Label Margin="20j0j5j2">Company Name:</Label> 

<Label Margin="20j0j 5j2">Phone:</Label> 

<Label Margin="20j0j 5j2">Address:</Label> 

<Label Margin="20j0j 5j2">City:</Label> 

<Label Margin="20j0j 5j 2">Region:</Label> 

<Label Margin="20j0j5j2">Postal Code:</Label> 

</StackPanel> 


Specifying Data Bindings 

The master list of customers is displayed in a ListBox control. The attached ListitemsTempiate binds a TextBlock 
control to the contactName field from the database. 







The details of each customer record are displayed in several TextBox controls. 

To specify data bindings 

• Copy the following XAML into the Grid element's declaration. 

The Binding class binds the TextBox controls to the appropriate fields in the database. 

<Stacl<Panel Orientation="Ver'tical" Grid.Row="0" Grid.Column="0"> 

<Label Mar'gin="20j5j5j0">List of Customers:</Label> 

<ListBox x:Name="listBoxl" Height="200" Width="200" HorizontalAlignment="Left" 

ItemTemplate="{StaticResource ListItemsTemplate}" IsSynchronizedWithCurrentItem="True" 
Margin="20,5j5,5"/> 

</StackPanel> 

<Stacl<Panel Orientation="Vertical" Grid.Row="0" Grid.Column="2"> 

<TextBox Margin="5,38j5j2" Width="200" Text="{Binding Path=ContactName}"/> 

<TextBox Margin="5,0,5,2" Width="200" Text="{Binding Path=CompanyName}"/> 

<TextBox Margln="5,0,5,2" Width="200" Text="{Binding Path=Phone}"/> 

<TextBox Margln="5,0,5,2" Width="200" Text="{Binding Path=Address}"/> 

<TextBox Margin="5,0j5,2" Width="200" Text="{Binding Path=City}"/> 

<TextBox Margin="5,0j5,2" Width="30" HorizontalAlignment="Left" Text="{Binding Path=Region}"/> 
<TextBox Margln="5,0,5,2" Width="50" HorizontalAlignment="Left" Text="{Binding Path=PostalCode}"/> 
</StackPanel> 


Displaying Data by Using Interoperation 

The orders corresponding to the selected customer are displayed in a System.Windows.Forms.DataGridView 
control named dataGridviewi .The dataGridViewi control is bound to the data Source in the code-behind file. A 
WindowsFormsHost control is the parent of this Windows Forms control. 

To display data in the DataGridView control 

• Copy the following XAML into the Grid element's declaration. 

<WindowsFormsHost Grid.Row="l" Grld.Column="0" Grid.ColumnSpan="3" Margin="20j5,5,5" Height="300"> 

<wf:DataGridView x:Mame="dataGridviewi"/> 

</WindowsFormsHost> 


Adding the Data Source to the Project 

With Visual Studio, you can easily add a data source to your project. This procedure adds a strongly typed data set 
to your project. Several other support classes, such as table adapters for each of the chosen tables, are also added. 

To add the data source 

1. From the Data menu, select Add New Data Source. 

2. In the Data Source Configuration Wizard, create a connection to the Northwind database by using a 
dataset. For more information, see How to: Connect to Data in a Database. 

3. When you are prompted by the Data Source Configuration Wizard, save the connection string as 

NorthwindConnectionString . 

4. When you are prompted to choose your database objects, select the customers and orders tables, and 
name the generated data set NorthwindDataSet . 

Binding to the Data Source 

The System.Windows.Forms.BindingSource component provides a uniform interface for the application's data 









source. Binding to the data source is implemented in the code-behind file. 

To bind to the data source 

1. Open the code-behind file, which is named MainWindow.xaml.vb or MainWindow.xaml.es. 

2. Copy the following code into the Mainwindow class definition. 

This code declares the BindingSource component and associated helper classes that connect to the database. 

private System.Windows.Forms.BindingSource nwBindingSourcej 
private NorthwindDataSet nwDataSet; 

private NorthwindDataSetTableAdapters.CustomersTableAdapter customersTableAdapter = 
new NorthwindDataSetTableAdapters.CustomersTableAdapter0; 
private NorthwindDataSetTableAdapters.OrdersTableAdapter ordersTableAdapter = 
new NorthwindDataSetTableAdapters.OrdersTableAdapter()j 


Private nwBindingSource As System.Windows.Forms.BindingSource 
Private nwDataSet As NorthwindDataSet 

Private customersTableAdapter As New NorthwindDataSetTableAdapters.CustomersTableAdapter() 
Private ordersTableAdapter As New NorthwindDataSetTableAdapters.OrdersTableAdapter() 


3. Copy the following code into the constructor. 

This code creates and initializes the BindingSource component. 

public MainWindowO 

{ 

InitializeComponentO; 

// Create a DataSet for the Customers data, 
this.nwDataSet = new NorthwindDataSet(); 
this.nwDataSet.DataSetName = "nwDataSet"; 

// Create a BindingSource for the Customers data, 
this.nwBindingSource = new System.Windows.Forms.BindingSource(); 
this.nwBindingSource.DataMember = "Customers"; 
this.nwBindingSource.DataSource = this.nwDataSet; 

} 


Public Sub New() 

InitializeComponentO 

' Create a DataSet for the Customers data. 

Me.nwDataSet = New NorthwindDataSet() 

Me.nwDataSet.DataSetName = "nwDataSet" 

' Create a BindingSource for the Customers data. 

Me.nwBindingSource = New System.Windows.Forms.BindingSource() 
Me.nwBindingSource.DataMember = "Customers" 

Me.nwBindingSource.DataSource = Me.nwDataSet 

End Sub 


4. Open MainWindow.xaml. 

5. In Design view or XAML view, select the Window element. 

6. In the Properties window, click the Events tab. 


7. Double-click the Loaded event. 







8. Copy the following code into the Loaded event handler. 


This code assigns the BindingSource component as the data context and populates the customers and 
Orders adapter objects. 

private void Window_Loaded(object sendetj RoutedEventArgs e) 

{ 

// Fill the Customers table adapter with data. 
this.customersTableAdapter.ClearBeforeFill = true; 
this.customersTableAdapter.Fill(this.nwDataSet.Customers); 

// Fill the Orders table adapter with data. 
this.ordersTableAdapter.Fill(this.nwDataSet.Orders); 

// Assign the BindingSource to 
// the data context of the main grid. 
this.mainGrid.DataContext = this.nwBindingSource; 

// Assign the BindingSource to 
// the data source of the list box. 
this.listBoxl.ItemsSource = this.nwBindingSource; 

// Because this is a master/details form^ the DataGridView 
// requires the foreign key relating the tables. 
this.dataGridViewl.DataSource = this.nwBindingSource; 
this.dataGridViewl.DataMember = "FK_Orders_Customers"; 

// Flandle the currency management aspect of the data models. 

// Attach an event handler to detect when the current item 
// changes via the WPF ListBox. This event handler synchronizes 
// the list collection with the BindingSource. 

// 

BindingListCollectionView cv = CollectionViewSource.GetDefaultView( 
this.nwBindingSource) as BindingListCollectionView; 

cv.CurrentChanged += new EventFlandler(WPF_CurrentChanged); 



Private Sub Window_Loaded( _ 

ByVal sender As Object, _ 

ByVal e As RoutedEventArgs) 

' Fill the Customers table adapter with data. 

Me.customersTableAdapter.ClearBeforeFill = True 
Me.customersTableAdapter.Fill(Me.nwDataSet.Customers) 

' Fill the Orders table adapter with data. 

Me.ordersTableAdapter.Fill(Me.nwDataSet.Orders) 

' Assign the BindingSource to 
' the data context of the main grid. 

Me.mainGrid.DataContext = Me.nwBindingSource 

' Assign the BindingSource to 
' the data source of the list box. 

Me.listBoxl.ItemsSource = Me.nwBindingSource 

' Because this is a master/details form, the DataGridView 
' requires the foreign key relating the tables. 

Me.dataGridViewl.DataSource = Me.nwBindingSource 
Me.dataGridViewl.DataMember = "FK_Orders_Customers" 

’ Handle the currency management aspect of the data models. 

' Attach an event handler to detect when the current item 
' changes via the WPF ListBox. This event handler synchronizes 
' the list collection with the BindingSource. 

Dim cv As BindingListCollectionView = _ 

CollectionViewSource.GetDefaultView(Me.nwBindingSource) 

AddHandler cv.CurrentChanged, AddressOf WPF_CurrentChanged 

End Sub 

9. Copy the following code into the MainWindow class definition. 

This method handles the CurrentChanged event and updates the current item of the data binding. 

// This event handler updates the current item 
// of the data binding. 

void WPF_CurrentChanged(object sender, EventArgs e) 

{ 

BindingListCollectionView cv = sender as BindingListCollectionViewj 
this.nwBindingSource.Position = cv.CurrentPositionj 

} 


' This event handler updates the current item 
' of the data binding. 

Private Sub WPF_CurrentChanged(ByVal sender As Object, ByVal e As EventArgs) 
Dim cv As BindingListCollectionView = sender 
Me.nwBindingSource.Position = cv.CurrentPosition 
End Sub 


10. Press F5 to build and run the application. 

See also 


• ElementHost 






WindowsFormsHost 

Design XAML in Visual Studio 

Data Binding in Hybrid Applications Sample 

Walkthrough; Hosting a Windows Forms Composite Control in WPF 

Walkthrough: Hosting a WPF Composite Control in Windows Forms 


Walkthrough: Host a 3D WPF Composite Control in 
Windows Forms 

1/28/2020 • 4 minutes to read • Edit Online 


This walkthrough demonstrates how you can create a WPF composite control and host it in Windows Forms 
controls and forms by using the ElementHost control. 

In this walkthrough, you will implement a WPF UserControl that contains two child controls. The UserControl 
displays a three-dimensional (3D) cone. Rendering 3D objects is much easier with the WPF than with Windows 
Forms. Therefore, it makes sense to host a WPF UserControl class to create 3D graphics in Windows Forms. 

Tasks illustrated in this walkthrough include: 

• Creating the WPF UserControl. 

• Creating the Windows Forms host project. 

• Hosting the WPF UserControl. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio 2017 

Create the UserControl 

1. Create a WPF User Control Library project named HostingWpfUserControiinWf . 

2. Open UserControll .xami in the WPF Designer. 

3. Replace the generated code with the following code: 

<UserContr'ol x:Class=" HostingWpfUserControiinWf .UserControll" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

<Grid> 

<!-- Place a Label control at the top of the view. --> 

<Label 

HorizontalAlignment="Center" 

TextBlock.TextAlignment="Center" 

FontSize="20" 

Foreground="Red" 

Content="Model: Cone"/> 

<!-- ViewportBD is the rendering surface. --> 

<Viewport3D Name="my\/iewport" > 

<!-- Add a camera. --> 

<Viewport3D.Camera> 

<PerspectiveCamera 

FarPlaneDistance="20" 

LookDirection="0j0jl" 

UpDirection="0jlj0" 





Near'h'laneLiistance='l' 
Position="0,0j-3" 
Field0fView="45" /> 

</Viewport 3D. Camer'a> 

<!-- Add models. --> 

<Viewport3D.Children) 

<ModelVisual3D> 

<ModelVisual3D.Content) 


<Model3DGroup ) 

<Model3DGroup.Children) 


<!-- Lightsj MeshGeometry3D and DiffuseMaterial objects are added to the 

ModelVisual3D. --) 

<DirectionalLight Color="#FFFFFFFF" Direction="3j-4,5" /) 

<!-- Define a red cone. --) 

<GeometryModel3D) 


<GeometryModel3D.Geometry) 

<MeshGeometry3D 

Positions="0.293893 -0.5 0.404509 0.475528 -0.5 0.154509 0 0.5 0 0.475528 -0.5 0.154509 0 0.5 0 

0 0.5 0 0.475528 -0.5 0.154509 0.475528 -0.5 -0.154509 0 0.5 0 0.475528 -0.5 -0.154509 0 0.5 0 0 

0.5 0 0.475528 -0.5 -0.154509 0.293893 -0.5 -0.404509 0 0.5 0 0.293893 -0.5 -0.404509 0 0.5 0 0 
0.5 0 0.293893 -0.5 -0.404509 0 -0.5 -0.5 0 0.5 0 0 -0.5 -0.5 0 0.5 0 0 0.5 0 0 -0.5 -0.5 - 
0.293893 -0.5 -0.404509 0 0.5 0 -0.293893 -0.5 -0.404509 0 0.5 0 0 0.5 0 -0.293893 -0.5 -0.404509 

-0.475528 -0.5 -0.154509 0 0.5 0 -0.475528 -0.5 -0.154509 0 0.5 0 0 0.5 0 -0.475528 -0.5 -0.154509 
-0.475528 -0.5 0.154509 0 0.5 0 -0.475528 -0.5 0.154509 0 0.5 0 0 0.5 0 -0.475528 -0.5 0.154509 - 
0.293892 -0.5 0.404509 0 0.5 0 -0.293892 -0.5 0.404509 0 0.5 0 0 0.5 0 -0.293892 -0.5 0.404509 0 - 
0.5 0.5 0 0.5 0 0 -0.5 0.5 0 0.5 0 0 0.5 0 0 -0.5 0.5 0.293893 -0.5 0.404509 0 0.5 0 0.293893 - 
0.5 0.404509 0 0.5 0 0 0.5 0 " 

Normals="0.7236065,0.4472139,0.5257313 0.2763934,0.4472138,0.8506507 0.5308242,0.4294462,0.7306172 

0.2763934,0.4472138,0.8506507 0,0.4294458,0.9030925 0.5308242,0.4294462,0.7306172 

-0.2763934,0.4472138,0.8506507 0,0.4294458,0.9030925 - 

-0.5308242,0.4294462,0.7306172 0,0.4294458,0.9030925 - 

-0.7236065,0.4472139,0.5257313 -0.5308242,0.4294462,0.7306172 - 

-0.858892,0.429446,0.279071 -0.5308242,0.4294462,0.7306172 - 

-0.8944269,0.4472139,0 -0.858892,0.429446,0.279071 - 

0.8944269,0.4472139,0 -0.858892,0.429446,-0.279071 -0.858892,0.429446,0.279071 -0.8944269,0.4472139,0 

-0.7236065,0.4472139,-0.5257313 -0.858892,0.429446,-0.279071 -0.7236065,0.4472139,-0.5257313 - 

0.5308242,0.4294462,-0.7306172 -0.858892,0.429446,-0.279071 -0.7236065,0.4472139,-0.5257313 - 

0.2763934,0.4472138,-0.8506507 -0.5308242,0.4294462,-0.7306172 -0.2763934,0.4472138,-0.8506507 

0,0.4294458,-0.9030925 -0.5308242,0.4294462,-0.7306172 -0.2763934,0.4472138,-0.8506507 

0.2763934,0.4472138,-0.8506507 0,0.4294458,-0.9030925 0.2763934,0.4472138,-0.8506507 

0.5308249,0.4294459,-0.7306169 0,0.4294458,-0.9030925 0.2763934,0.4472138,-0.8506507 

0.7236068,0.4472141,-0.5257306 0.5308249,0.4294459,-0.7306169 0.7236068,0.4472141,-0.5257306 

0.8588922,0.4294461,-0.27907 0.5308249,0.4294459,-0.7306169 0.7236068,0.4472141,-0.5257306 

0.8944269,0.4472139,0 0.8588922,0.4294461,-0.27907 0.8944269,0.4472139,0 0.858892,0.429446,0.279071 

0.8588922,0.4294461,-0.27907 0.8944269,0.4472139,0 0.7236065,0.4472139,0.5257313 

0.858892,0.429446,0.279071 0.7236065,0.4472139,0.5257313 0.5308242,0.4294462,0.7306172 

0.858892,0.429446,0.279071 " TriangleIndices="0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 

16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 
51 52 53 54 55 56 57 58 59 " /) 

</GeometryModel3D.Geometry) 


0.2763934,0.4472138,0.8506507 

0.2763934,0.4472138,0.8506507 

0.2763934,0.4472138,0.8506507 

0.7236065,0.4472139,0.5257313 

0.7236065,0.4472139,0.5257313 


<GeometryModel3D.Material) 
<DiffuseMaterial) 

<DiffuseMaterial.Brush) 
<SolidColorBrush 
Color="Red" 
Opacity="1.0"/) 

</DiffuseMaterial.Brush) 
</DiffuseMaterial) 
</GeometryModel3D.Material) 


</GeometryModel3D) 


</Model3DGroup.Children> 

</Model3DGroup> 

</ModelVisual3D.Content> 

</ModelVisual3D> 

</Viewport3D.Children> 

</Viewport3D> 

</Grid> 

</UserControl> 

This code defines a System.Windows.Controls.UserControl that contains two child controls. The first child 
control is a System.Windows.Controls.Label control; the second is a ViewportSD control that displays a 3D 
cone. 

Create the host project 

1. Add a Windows Forms App (.NET Framework) project named wpfUserControiHost to the solution. 

2. In Solution Explorer, add a reference to the WindowsFormsIntegration assembly, which is named 
WindowsFormslntegration.dll. 

3. Add references to the following WPF assemblies: 

• PresentationCore 

• PresentationFramework 

• WindowsBase 


4. Add a reference to the HostingWpfUserControimwf project. 

5. In Solution Explorer, set the wpfUserControiHost project to be the startup project. 


Host the UserControl 

1. In the Windows Forms Designer, open Formi. 

2. In the Properties window, click Events, and then double-click the Load event to create an event handler. 

The Code Editor opens to the newly generated Formi_Load event handler. 

3. Replace the code in Formi .cs with the following code. 

The For'mi_Load event handler creates an instance of userControii and adds itto the ElementHost control's 
collection of child controls. The ElementHost control is added to the form's collection of child controls. 








using System; 

using System.Collections.Generic; 

using System.ComponentModel; 

using System.Data; 

using System.Drawing; 

using System.Text; 

using System.Windows.Forms; 

using System.Windows.Forms.Integration; 

namespace WpfUserControlFlost 

{ 

public partial class Forml : Form 

{ 

public FormlO 

{ 

InitializeComponent(); 

} 

private void Forml_Load(object sender, EventArgs e) 

{ 

// Create the ElementFlost control for hosting the 
// WPF UserControl. 

ElementFlost host = new ElementFlost(); 
host.Dock = DockStyle.Fill; 

// Create the WPF UserControl. 

FlostingWpfUserControlInWf.UserControll uc = 

new FlostingWpfUserControlInWf.UserControll(); 

// Assign the WPF UserControl to the ElementFlost control's 
// Child property, 
host.Child = uc; 

// Add the ElementFlost control to the form's 
// collection of child controls, 
this.Controls.Add(host); 

} 

} 

} 



Imports System.Collections.Generic 

Imports System.ComponentModel 

Imports System.Data 

Imports System.Drawing 

Imports System.Text 

Imports System.Windows.Forms 

Imports System.Windows.Forms.Integration 

Public Class Forml 
Inherits Form 

Private Sub Forml_Load(ByVal sender As System.Objectj ByVal e As System.EventArgs) Handles 
MyBase.Load 

' Create the ElementHost control for hosting the 
' WPF UserControl. 

Dim host As New ElementHost() 
host.Dock = DockStyle.Fill 

' Create the WPF UserControl. 

Dim uc As New HostingWpfUserControlInWf.UserControll() 

' Assign the WPF UserControl to the ElementHost control's 
' Child property, 
host.Child = uc 

' Add the ElementHost control to the form's 
' collection of child controls. 

Me.Controls.Add(host) 

End Sub 

End Class 


4. Press F5 to build and run the application. 

See also 

• ElementHost 

• WindowsFormsHost 

• Design XAML in Visual Studio 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 

• Walkthrough: Hosting a Windows Forms Composite Control in WPF 

• Hosting a WPF Composite Control in Windows Forms Sample 



Walkthrough: Hosting a WPF Composite Control in 
Windows Forms 

3/27/2020 • 17 minutes to read « Edit Online 


Windows Presentation Foundation (WPF) provides a rich environment for creating applications. However, when 
you have a substantial investment in Windows Forms code, it can be more effective to extend your existing 
Windows Forms application with WPF rather than to rewrite it from scratch. A common scenario is when you 
want to embed one or more controls implemented with WPF within your Windows Forms application. For more 
information about customizing WPF controls, see Control Customization. 

This walkthrough steps you through an application that hosts a WPF composite control to perform data-entry in 
a Windows Forms application. The composite control is packaged in a DLL. This general procedure can be 
extended to more complex applications and controls. This walkthrough is designed to be nearly identical in 
appearance and functionality to Walkthrough: Hosting a Windows Forms Composite Control in WPF. The 
primary difference is that the hosting scenario is reversed. 

The walkthrough is divided into two sections. The first section briefly describes the implementation of the WPF 
composite control. The second section discusses in detail how to host the composite control in a Windows 
Forms application, receive events from the control, and access some of the control's properties. 

Tasks illustrated in this walkthrough include: 

• Implementing the WPF composite control. 

• Implementing the Windows Forms host application. 

For a complete code listing of the tasks illustrated in this walkthrough, see Hosting a WPF Composite Control in 
Windows Forms Sample. 

Prerequisites 

You need Visual Studio to complete this walkthrough. 

Implementing the WPF Composite Control 

The WPF composite control used in this example is a simple data-entry form that takes the user's name and 
address. When the user clicks one of two buttons to indicate that the task is finished, the control raises a custom 
event to return that information to the host. The following illustration shows the rendered control. 


The following image shows a WPF composite control: 


Simple WPF Control 

Name 


Street Address 





City 

State 

Zip 


OK 

Cancel 



Creating the Project 







To start the project: 

1. Launch Visual Studio, and open the New Project dialog box. 

2. In Visual C# and the Windows category, select the WPF User Control Library template. 

3. Name the new project MyContnois . 

4. For the location, specify a conveniently named top-level folder, such as windowsFormsHostingWpfControi . 

Later, you will put the host application in this folder. 

5. Click OK to create the project. The default project contains a single control named userContnoii . 

6. In Solution Explorer, rename usenControii to MyContnoii . 

Your project should have references to the following system DLLs. If any of these DLLs are not included by 
default, add them to your project. 

• PresentationCore 

• PresentationFramework 

• System 

• WindowsBase 

Creating the User Interface 

The user interface (Ul) for the composite control is implemented with Extensible Application Markup Language 
(XAML). The composite control Ul consists of five TextBox elements. Each TextBox element has an associated 
TextBlock element that serves as a label. There are two Button elements at the bottom, OK and Cancel. When 
the user clicks either button, the control raises a custom event to return the information to the host. 

Basic Layout 

The various Ul elements are contained in a Grid element. You can use Grid to arrange the contents of the 
composite control in much the same way you would use a Table element in HTML. WPF also has a Table 
element, but Grid is more lightweight and better suited for simple layout tasks. 

The following XAML shows the basic layout. This XAML defines the overall structure of the control by specifying 
the number of columns and rows in the Grid element. 

In MyControll .xami, replace the existing XAML with the following XAML. 








<Grid xtiilns="http://schemas.micnosoft. com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
x:Class="MyContr'ols .MyControll" 

Bacl<gr'ound="#DCDCDC" 

Width="375" 

Height="250" 

Name="rootElement" 

Loaded="Init"> 

<Grid.ColumnDefinitions> 

<ColumnDefinition Width="Auto" /> 

<ColumnDefinition Width="Auto" /> 

<ColumnDefinition Width="Auto"/> 

<ColumnDefinition Width="Auto"/> 

</Grid.ColumnDefinitions> 

<Grid.RowDefinitions> 

<RowDefinition Height="Auto" /> 

<RowDefinition Height="Auto" /> 

<RowDefinition Height="Auto" /> 

<RowDefinition Height="Auto" /> 

<RowDefinition Height="Auto" /> 

<RowDefinition Height="Auto" /> 

</Grid.RowDefinitions> 


</Grid> 

Adding TextBlock and TextBox Elements to the Grid 

You place a Ul element in the grid by setting the element's RowProperty and ColumnProperty attributes to the 
appropriate row and column number. Remember that row and column numbering are zero-based. You can have 
an element span multiple columns by setting its ColumnSpanProperty attribute. For more information about 
Grid elements, see Create a Grid Element. 

The following XAML shows the composite control's TextBox and TextBlock elements with their RowProperty and 
ColumnProperty attributes, which are set to place the elements properly in the grid. 


In MyControll .xami, add the following XAML within the Grid element. 



<TextBlocl< Grid.Column="0" 

Grid.Row="0" 

Gr'id.ColumnSpan="4" 

Margin="10,5,10J 0" 

HorizontalAlignment="Center" 

Style="{StaticResource titleText}">Simple WPF Control</TextBlock> 

<TextBlocl< Grid.Column="0" 

Grid.Row="l" 

Style="{StaticResource inlineText}" 

Name="nameLabel">Name</TextBlock> 

<TextBox Grid.Column="l" 

Grid.Row="l" 

Grid.ColumnSpan="3" 

Name="txtName"/> 

<TextBlock Grid.Column="0" 

Grid.Row="2" 

Style="{StaticResource inlineText}" 

Name="addressLabel">Street Address</TextBlock> 

<TextBox Grid.Column="l" 

Grid.Row="2" 

Grid.ColumnSpan="3" 

Name="txtAddress"/> 

<TextBlock Grid.Column="0" 

Grid.Row="3" 

Style="{StaticResource inlineText}" 

Name="cityLabel">City</TextBlock> 

<TextBox Grid.Column="l" 

Grid.Row="3" 

Wldth="100" 

Name="txtCity"/> 

<TextBlock Grid.Column="2" 

Grid.Row="3" 

Style="{StaticResource inlineText}" 

Name="stateLabel">State</TextBlock> 

<TextBox Grid.Column="3" 

Grid.Row="3" 

Width="50" 

Name="txtState"/> 

<TextBlock Grid.Column="0" 

Grid.Row="4" 

Style="{StaticResource inlineText}" 

Name="zipLabel">Zip</TextBlock) 

<TextBox Grid.Column="l" 

Grid.Row="4" 

Width="100" 

Name="txtZip"/> 

Styling the Ul Elements 

Many of the elements on the data-entry form have a similar appearance, which means that they have identical 
settings for several of their properties. Rather than setting each element's attributes separately, the previous 
XAML uses Style elements to define standard property settings for classes of elements. This approach reduces 
the complexity of the control and enables you to change the appearance of multiple elements through a single 
style attribute. 

The Style elements are contained in the Grid element's Resources property, so they can be used by all elements 
in the control. If a style is named, you apply it to an element by adding a Style element set to the style's name. 
Styles that are not named become the default style for the element. For more information about WPF styles, see 
Styling and Templating. 



The following XAML shows the Style elements for the composite control. To see how the styles are applied to 
elements, see the previous XAML. For example, the last TextBlock element has the iniinetext style, and the last 
TextBox element uses the default style. 

In MyControll.xamI, add the following XAML just after the Grid start element. 

<Grid. Resour'ces> 

<Style x:Key="inlineText" TargetType="{x:Type TextBlock}"> 

<Setter Property="Margin" Value="10j5,10j0"/> 

<Setter Pr'oper'ty="FontWeight" Value="Normal"/> 

<Setter Pr'oper'ty="FontSize" Value="12"/> 

</Style> 

<Style x:Key="titleText" TargetType="{x:Type TextBlock}"> 

<Setter Pr'oper'ty="DockPanel.Dock" Value="Top"/> 

<Setter Pr'oper'ty="FontWeight" Value="Bold"/> 

<Setter Property="FontSize" Value="14"/> 

<Setter Property="Margin" Value="10j5,10j0"/> 

</Style> 

<Style Tar'getType="{x:Type Button}"> 

<Setter Pr'oper'ty="Margin" Value="10j5,10j0"/> 

<Setter Property="Width" Value="60"/> 

</Style> 

<Style Tar'getType="{x:Type TextBox}"> 

<Setter Pr'oper'ty="Margin" Value="10j5,10j0"/> 

</Style> 

</Grid.Resources> 

Adding the OK and Cancel Buttons 

The final elements on the composite control are the OK and Cancel Button elements, which occupy the first two 
columns of the last row of the Grid. These elements use a common event handler, Buttonciicked , and the 
default Button style defined in the previous XAML. 

In MyControll.xamI, add the following XAML after the last TextBox element. The XAML part of the composite 
control is now complete. 

<Button Grid.Row="5" 

Grid.Column="0" 

Name="btnOK" 

Click="ButtonClicked">OK</Button> 

<Button Grid.Row="5" 

Grid.Column="l" 

Name="btnCancel" 

Click="ButtonClicked">Cancel</Button> 


Implementing the Code-Behind File 

The code-behind file, MyControM .xaml.cs, implements three essential tasks: 

1. Handles the event that occurs when the user clicks one of the buttons. 

2. Retrieves the data from the TextBox elements, and packages it in a custom event argument object. 

3. Raises the custom onButtonciick event, which notifies the host that the user is finished and passes the 
data back to the host. 

The control also exposes a number of color and font properties that enable you to change the appearance. 
Unlike the WindowsFormsHost class, which is used to host a Windows Forms control, the ElementHost class 
exposes the control's Background property only. To maintain the similarity between this code example and the 
example discussed in Walkthrough: Hosting a Windows Forms Composite Control in WPF, the control exposes 
the remaining properties directly. 







The Basic Structure of the Code-Behind File 


The code-behind file consists of a single namespace, MyControis , which will contain two classes, MyContnoii 
and MyControlEventAngs . 


namespace MyControis 


{ 



public 

{ 

//... 

} 

partial class MyControii : 

: Grid 

public 

{ 

//... 

} 

} 

class MyControiEventArgs : 

: EventArgs 


The first class, MyControii , is a partial class containing the code that implements the functionality of the Ul 
defined in MyControii .xaml. When MyControii.xami is parsed, the XAML is converted to the same partial class, 
and the two partial classes are merged to form the compiled control. For this reason, the class name in the code- 
behind file must match the class name assigned to MyControii.xaml, and it must inherit from the root element 
of the control. The second class, MyControiEventArgs , is an event arguments class that is used to send the data 
back to the host. 

Open MyControii .xaml.cs. Change the existing class declaration so that it has the following name and inherits 
from Grid. 

public partial class MyControii : Grid 

Initializing the Control 

The following code implements several basic tasks: 

• Declares a private event, onButtonciick , and its associated delegate, MyControiEventHandier . 

• Creates several private global variables that store the user's data. This data is exposed through 
corresponding properties. 

• Implements a handler, init , for the control's Loaded event. This handler initializes the global variables by 
assigning them the values defined in MyControii .xaml. To do this, it uses the Name assigned to a typical 
TextBlock element, nameiabei , to access that element's property settings. 

Delete the existing constructor and add the following code to your MyControii class. 














public delegate void MyContr'olEventHandler(object sendeCj MyControlEventArgs args)j 

public event MyContnolEventHandler OnButtonClick; 

private FontWeight _fontWeight; 

private double _fontSize; 

private FontFamily _fontFamily; 

private FontStyle _fontStyle; 

private SolidColorBrush _foreground; 

private SolidColorBrush _background; 

private void Init(object sender^ EventArgs e) 

{ 

//They all have the same style, so use nameiabel to set initial values. 

_fontWeight = nameiabel.FontWeight; 

_fontSize = nameiabel.FontSize; 

_fontFamily = nameiabel.FontFamily; 

_fontStyle = nameiabel.FontStyle; 

_foreground = (SolidColorBrush)nameiabel.Foreground; 

_background = (SolidColorBrush)rootElement.Background; 

} 

Handling the Buttons' Click Events 

The user indicates that the data-entry task is finished by clicking either the OK button or the Cancel button. 
Both buttons use the same Click event handler, Buttonciicked . Both buttons have a name, btnOK or btnCancei , 
that enables the handler to determine which button was clicked by examining the value of the sender 
argument. The handler does the following: 

• Creates a MyControlEventArgs object that contains the data from the TextBox elements. 

• If the user clicked the Cancel button, sets the MyControlEventArgs object's isok property to false. 

• Raises the onButtonciick event to indicate to the host that the user is finished, and passes back the 
collected data. 

Add the following code to your MyControii class, after the init method. 

private void ButtonClicked(object sender, RoutedEventArgs e) 

{ 

MyControlEventArgs retvals = new MyControlEventArgs(true, 

txtName.Text, 
txtAddress.Text, 
txtCity.Text, 
txtState.Text, 
txtZip.Text); 

if (sender == btnCancel) 

{ 

retvals.IsOK = false; 

} 

if (OnButtonClick != null) 

OnButtonClick(this, retvals); 

} 

Creating Properties 

The remainder of the class simply exposes properties that correspond to the global variables discussed 
previously. When a property changes, the set accessor modifies the appearance of the control by changing the 
corresponding element properties and updating the underlying global variables. 

Add the following code to your MyControii class. 

public FontWeight MyControl_FontWeight 

{ 

get { return _fontWeight; } 














set 

{ 

_fontWeight = value; 
nameLabel.FontWeight = value; 
addnessLabel.FontWeight = value; 
cityLabel.FontWeight = value; 
stateLabel.FontWeight = value; 
zipLabel.FontWeight = value; 

} 

} 

public double MyControl_FontSlze 

{ 

get { return _fontSize; } 

set 

{ 

_fontSize = value; 
nameLabel.FontSize = value; 
addnessLabel.FontSize = value; 
cityLabel.FontSize = value; 
StateLabel.FontSize = value; 
zipLabel.FontSize = value; 

} 

} 

public FontStyle MyContnol_FontStyle 

{ 

get { return _fontStylej } 

set 

{ 

_fontStyle = value; 
nameLabel.FontStyle = value; 
addnessLabel.FontStyle = value; 
cityLabel.FontStyle = value; 
StateLabel.FontStyle = value; 
zipLabel.FontStyle = value; 

} 

} 

public FontFamily MyContnol_FontFamily 

{ 

get { return _fontFamily; } 

set 

{ 

_fontFamily = value; 
nameLabel.FontFamily = value; 
addnessLabel.FontFamily = value; 
cityLabel.FontFamily = value; 
StateLabel.FontFamily = value; 
zipLabel.FontFamily = value; 

} 


public SolidColonBnush MyContnol_Backgnound 

{ 

get { return _bacl<ground; } 

set 

{ 

_backgnound = value; 
nootElement.Backgnound = value; 

} 

} 

public SolidColonBnush MyContnol_Fonegnound 

{ 

get { return _foreground; } 

set 

{ 

_fonegnound = value; 
nameLabel.Fonegnound = value; 
addnessLabel.Fonegnound = value; 
cityLabel.Fonegnound = value; 
StateLabel.Fonegnound = value; 


zipLabel.Foreground = value; 

} 

} 

Sending the Data Back to the Host 

The final component in the file is the MyControiEventArgs class, which is used to send the collected data back to 
the host. 

Add the following code to your MyControis namespace. The implementation is straightforward, and is not 
discussed further. 




public class MyContnolEventArgs : EventArgs 

{ 

private string _Name; 
private string _StreetAddress; 
private string _City; 
private string _State; 
private string _Zip; 
private bool _IsOK; 

public MyControlEventArgs(bool result, 

string name, 
string address, 
string city, 
string state, 
string zip) 

{ 

_IsOK = result; 

_Name = name; 

_StreetAddress = address; 

_City = city; 

_State = state; 

_Zip = zip; 

} 

public string MyName 

{ 

get { return _Name; } 
set { _Name = value; } 

} 

public string MyStreetAddress 

{ 

get { return _StreetAddress; } 
set { _StreetAddress = value; } 

} 

public string MyCity 

{ 

get { return _City; } 
set { _City = value; } 

} 

public string MyState 

{ 

get { return _State; } 
set { _State = value; } 

} 

public string MyZip 

{ 

get { return _Zip; } 
set { _Zip = value; } 

} 

public bool IsOK 

{ 

get { return _IsOK; } 
set { _IsOK = value; } 

} 


Build the solution. The build will produce a DLL named MyControls.dll. 

Implementing the Windows Forms Host Application 

The Windows Forms host application uses an ElementHost object to host the WPF composite control. The 
application handles the Onsuttonciick event to receive the data from the composite control. The application 
also has a set of option buttons that you can use to modify the control's appearance. The following illustration 
shows the application. 




The following image shows a WPF composite control hosted in a Windows Forms application' 


I— Windows Form Hosting WPF Control 

■Simple WPF Control 
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Background Color 
O Original 
O LightGreen 
O LightSalmon 


Data From Control 

Name: 

Street Address; 

City: 

State: 

Zip: 


Foreground Color 
O Original 
O Red 
O Yellow 

Font Family 
O Original 

O Times New Roman 
O WingDings 


Creating the Project 

To start the project: 

1 . Launch Visual Studio, and open the New Project dialog box. 

2. In Visual C# and the Windows category, select the Windows Forms Application template. 

3. Name the new project WFHost . 

4. For the location, specify the same top-level folder that contains the MyControls project. 

5. Click OK to create the project. 

You also need to add references to the DLL that contains MyControii and other assemblies. 

1. Right-click the project name in Solution Explorer, and select Add Reference. 

2. Click the Browse tab, and browse to the folder that contains MyControls.dll. For this walkthrough, this 
folder is MyControls\bin\Debug. 

3. Select MyControls.dll, and then click OK. 

4. Add references to the following assemblies. 

• PresentationCore 

• PresentationFramework 

• System.XamI 

• WindowsBase 

• WindowsFormsIntegration 

Implementing the User Interface for the Application 

The Ul for the Windows Form application contains several controls to interact with the WPF composite control. 

1. Open Formi in the Windows Form Designer. 

2. Enlarge the form to accommodate the controls. 

3. In the upper-right corner of the form, add a System.Windows.Forms.Panel control to hold the WPF 











composite control. 


4. Add the following System.Windows.Forms.GroupBox controls to the form. 


NAME 

TEXT 


groupBoxI 

Background Color 


groupBox2 

Foreground Color 


groupBoxB 

Font Size 


groupBox4 

Font Family 


groupBoxB 

Font Style 


groupBoxB 

Font Weight 


groupBox? 

Data from control 


Add the following System.Windows.Forms.RadioButton controls to the System.Windows.Forms.GroupBox 

controls. 

GROUPBOX 

NAME 

TEXT 

groupBoxI 

radioBackgroundOriginal 

Original 

groupBoxI 

radioBackgroundLightGreen 

LightGreen 

groupBoxI 

radioBackgroundLightSalmon 

LightSalmon 

groupBox2 

radioForegroundOriginal 

Original 

groupBox2 

radioForegroundFted 

Fted 

groupBox2 

radioForegroundYellow 

Yellow 

groupBoxB 

radioSizeOriginal 

Original 

groupBoxB 

radioSizeTen 

10 

groupBoxB 

radioSizeTwelve 

12 

groupBox4 

radioFamilyOriginal 

Original 

groupBox4 

radioFamilyTimes 

Times New Roman 

groupBox4 

radioFamilyWingDings 

WingDings 

groupBoxB 

radioStyleOriginal 

Normal 

groupBoxB 

radioStyleltalic 

Italic 


GROUPBOX 

NAME 

TEXT 

groupBox6 

radioWeightOriginal 

Original 

groupBox6 

radioWeightBold 

Bold 

Add the following System.Windows.Forms.Label controls to the last System.Windows.Forms.GroupBox. 

These controls display the data returned by the WPF composite control. 

GROUPBOX 

NAME 

TEXT 

groupBox? 

IblName 

Name: 

groupBox? 

IblAddress 

Street Address: 

groupBox? 

IbICity 

City: 

groupBox? 

IbIState 

State: 

groupBox? 

IbIZip 

Zip: 


Initializing the Form 

You generally implement the hosting code in the form's Load event handler. The following code shows the Load 
event handler, a handler for the WPF composite control's Loaded event, and declarations for several global 
variables that are used later. 

In the Windows Forms Designer, double-click the form to create a Load event handler. At the top of Formi .cs, 
add the following using statements. 

using System.Windows; 

using System.Windows.Forms.Integration; 

using System.Windows.Media; 


Replace the contents of the existing Formi class with the following code. 





private ElementHost ctrlHost; 

private MyControls.MyControll wpfAddressCtrl; 

System.Windows.FontWeight initFontWeightj 
double initFontSize; 

System.Windows.FontStyle initFontStyle; 

System.Windows.Media.SolidColorBrush initBackBrush; 

System.Windows.Media.SolidColorBrush initForeBrushj 
System.Windows.Media.FontFamily initFontFamily; 

public Forml() 

{ 

InitializeComponent(); 

} 

private void Forml_Load(object sender^ EventArgs e) 

{ 

ctrlHost = new ElementHost(); 
ctrlHost.Dock = DockStyle.Fill; 
panell.Controls.Add(ctrlHost); 
wpfAddressCtrl = new MyControls.MyControll(); 
wpfAddressCtrl.InitializeComponent(); 

CtrlHost.Child = wpfAddressCtrl; 

wpfAddressCtrl.OnButtonClick += 

new MyControls.MyControll.MyControlEventHandler( 
avAddressCtrl_OnButtonClick); 
wpfAddressCtrl.Loaded += new RoutedEventHandler( 
avAddressCtrl_Loaded); 

} 

void avAddressCtrl_Loaded(object sender^ EventArgs e) 

{ 

initBackBrush = (SolidColorBrush)wpfAddressCtrl.MyControl_Background; 
initForeBrush = wpfAddressCtrl.MyControl_Foreground; 
initFontFamily = wpfAddressCtrl.MyControl_FontFamily; 
initFontSize = wpfAddressCtrl.MyControl_FontSize; 
initFontWeight = wpfAddressCtrl.MyControl_FontWeight; 
initFontStyle = wpfAddressCtrl.MyControl_FontStyle; 

} 

The Formi_Load method in the preceding code shows the general procedure for hosting a WPF control: 

1. Create a new ElementHost object. 

2. Set the control's Dock property to DockStyle.Fill. 

3. Add the ElementHost control to the Panel control's Controls collection. 

4. Create an instance of the WPF control. 

5. Host the composite control on the form by assigning the control to the ElementHost control's Child 
property. 

The remaining two lines in the Formi_Load method attach handlers to two control events: 

• onButtonciick is a custom event that is fired by the composite control when the user clicks the OK or 
Cancel button. You handle the event to get the user's response and to collect any data that the user 
specified. 

• Loaded is a standard event that is raised by a WPF control when it is fully loaded. The event is used here 
because the example needs to initialize several global variables using properties from the control. At the 
time of the form's Load event, the control is not fully loaded and those values are still set to null . You 
need to wait until the control's Loaded event occurs before you can access those properties. 







The Loaded event handler is shown in the preceding code. The onButtonciick handler is discussed in the next 
section. 

Handling OnButtonClick 

The OnButtonClick event occurs when the user clicks the OK or Cancel button. 

The event handler checks the event argument's isok field to determine which button was clicked. The ibi data 
variables correspond to the Label controls that were discussed earlier. If the user clicks the OK button, the data 
from the control's TextBox controls is assigned to the corresponding Label control. If the user clicks Cancel, the 
Text values are set to the default strings. 

Add the following button click event handler code to the Fonmi class. 

void avAddressCtrl_OnButtonClick( 
object sender^ 

MyControls.MyContnoll.MyControlEventArgs args) 

{ 

if (args.IsOK) 

{ 

IblAddress.Text = "Street Address: " + args.MyStreetAddress; 

IblCity.Text = "City: " + args.MyCity; 

IbllMame.Text = "Name: " + args.MyName; 

IblState.Text = "State: " + args.MyStatej 
IblZip.Text = "Zip: " + args.MyZipj 

} 

else 

{ 

IblAddress.Text = "Street Address: "j 
IblCity.Text = "City: 

IblName.Text = "Name: 

IblState.Text = "State: 

IblZip.Text = "Zip: 

} 

} 


Build and run the application. Add some text in the WPF composite control and then click OK. The text appears in 
the labels. At this point, code has not been added to handle the radio buttons. 

Modifying the Appearance of the Control 

The RadioButton controls on the form will enable the user to change the WPF composite control's foreground 
and background colors as well as several font properties. The background color is exposed by the ElementHost 
object. The remaining properties are exposed as custom properties of the control. 

Double-click each RadioButton control on the form to create CheckedChanged event handlers. Replace the 
CheckedChanged event handlers with the following code. 

private void radioBackgroundOriginal_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_Background = initBackBrush; 

} 

private void radioBackgroundLightGreen_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_Background = new SolidColorBrush(Colors.LightGreen); 

} 

private void radioBackgroundLightSalmon_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_Background = new SolidColorBrush(Colors.LightSalmon); 

} 


private void radioForegroundOriginal CheckedChanged(ob1ect sender, EventArgs e) 








{ 


wpfAddressCtrl.MyControl_For'eground = initFoneBrush; 


} 

private void radioForegroundRed_CheckedChanged(object sendetj EventArgs e) 

{ 

wpfAddressCtrl.MyControl_Foreground = new System.Windows.Media.SolidColorBrush(Colors.Red); 

} 

private void radioForegroundYellow_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_Foreground = new System.Windows.Media.SolidColorBrush(Colors.Yellow); 

} 

private void radioFamilyOriginal_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontFamily = initFontFamily; 

} 

private void radioFamilyTimes_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontFamily = new System.Windows.Media.FontFamilyC'Times New Roman"); 

} 

private void radioFamilyWingDings_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontFamily = new System.Windows.Media.FontFamilyC'WingDings"); 

} 

private void radioSizeOriginal_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontSize = initFontSize; 

} 

private void radioSizeTen_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontSize = 10; 

} 

private void radioSizeTwelve_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontSize = 12; 

} 

private void radioStyleOriginal_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontStyle = initFontStyle; 

} 

private void radioStyleItalic_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontStyle = System.Windows.FontStyles.Italic; 

} 

private void radioWeightOriginal_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontWeight = initFontWeight; 

} 

private void radioWeightBold_CheckedChanged(object sender, EventArgs e) 

{ 

wpfAddressCtrl.MyControl_FontWeight = FontWeights.Bold; 

} 

Build and run the application. Click the different radio buttons to see the effect on the WPF composite control. 


See also 


• ElementHost 

• WindowsFormsHost 

• Design XAML in Visual Studio 

• Walkthrough: Hosting a Windows Fornns Composite Control in WPF 

• Walkthrough: Hosting a 3D WPF Composite Control in Windows Forms 


Walkthrough: Mapping Properties Using the 
ElementHost Control 

1/28/2020 « 7 minutes to read • Edit Online 


This walkthrough shows you how to use the PropertyMap property to map Windows Forms properties to 
corresponding properties on a hosted WPF element. 

Tasks illustrated in this walkthrough include: 

• Creating the project. 

• Defining a new property mapping. 

• Removing a default property mapping. 

• Extending a default property mapping. 

For a complete code listing of the tasks illustrated in this walkthrough, see Mapping Properties Using the 
ElementHost Control Sample. 

When you are finished, you will be able to map Windows Forms properties to corresponding WPF properties on a 
hosted element. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio 2017 

Creating the Project 

To create the project 

1. Create a Windows Forms App project named PropertyMappingWithEiementHost . 

2. In Solution Explorer, add references to the following WPF assemblies. 

• PresentationCore 

• PresentationFramework 

• WindowsBase 

• WindowsFormsIntegration 

3. Copy the following code into the top of the Formi codefile. 

using System.Windows; 
using System.Windows.Media; 
using System.Windows.Media.Imaging; 
using System.Windows.Forms.Integration; 






Imports System.Windows 
Imports System.Windows.Media 
Imports System.Windows.Media.Imaging 
Imports System.Windows.Forms.Integration 

4. Open Formi in the Windows Forms Designer. Double-click the form to add an event handler for the Load 
event. 

5. Return to the Windows Forms Designer and add an event handler for the form's Resize event. For more 
information, see How to; Create Event Handlers Using the Designer. 

6. Declare an ElementHost field in the Formi class. 

ElementHost elemHost = null; 

Private elemHost As ElementHost = Nothing 


Defining New Property Mappings 

The ElementHost control provides several default property mappings. You add a new property mapping by calling 
the Add method on the ElementHost control's PropertyMap. 

To define new property mappings 

1. Copy the following code into the definition for the Formi class. 

// The AddMarginMapping method adds a new property mapping 
// for the Margin property, 
private void AddMarginMappingO 
{ 

elemHost.PropertyMap. Add( 

"Margin"j 

new PropertyTranslator(OnMarginChange)); 

} 

// The OnMarginChange method implements the mapping 
// from the Windows Forms Margin property to the 
// Windows Presentation Foundation Margin property. 

// 

// The provided Padding value is used to construct 
// a Thickness value for the hosted element's Margin 
// property. 

private void OnMarginChange(object h^ String propertyName, object value) 

{ 

ElementHost host = h as ElementHost; 

Padding p = (Padding)value; 

System.Windows.Controls.Button wpfButton = 

host.Child as System.Windows.Controls.Button; 

Thickness t = new Thickness(p.Left, p.Top, p.Right, p.Bottom ); 

wpfButton.Margin = t; 

} 






' The AddManginMapping method adds a new property mapping 
' for the Margin property. 

Private Sub AddMarginMappingO 

elemHost.PropertyMap.Add( _ 

"Margin"j _ 

New PropertyTranslator(AddressOf OnMarginChange)) 

End Sub 


' The OnMarginChange method implements the mapping 
' from the Windows Forms Margin property to the 
' Windows Presentation Foundation Margin property. 

' The provided Padding value is used to construct 
' a Thickness value for the hosted element's Margin 
' property. 

Private Sub OnMarginChange( _ 

ByVal h As Object^ _ 

ByVal propertyName As String, _ 

ByVal value As Object) 

Dim host As ElementFlost = h 

Dim p As Padding = CType(value, Padding) 

Dim wpfButton As System.Windows.Controls.Button = host.Child 

Dim t As New Thickness(p.Left, p.Top, p.Right, p.Bottom) 
wpfButton.Margin = t 
End Sub 

The AddManginMapping method adds a new mapping for the Margin property. 

The OnMarginChange method transiates the Margin property to the WPF Margin property. 


2. Copy the foiiowing code into the definition for the Formi ciass. 







// The AddRegionMapping method assigns a custom 
// mapping for the Region property, 
private void AddRegionMappingO 
{ 

elemHost.PropertyMap. Add( 

"Region"j 

new PropertyTranslator(OnRegionChange)); 

} 

// The OnRegionChange method assigns an EllipseGeometry to 
// the hosted element's Clip property, 
private void OnRegionChange( 
object h. 

String propertyNamej 
object value) 

{ 

ElementHost host = h as ElementHost; 

System.Windows.Controls.Button wpfButton = 

host.Child as System.Windows.Controls.Button; 

wpfButton.Clip = new EllipseGeometry(new Rect( 

0 . 

0 . 

wpfButton.ActualWidthj 
wpfButton.ActualHeight)); 

} 

// The Forml_Resize method handles the form's Resize event. 
// It calls the OnRegionChange method explicitly to 
// assign a new clipping geometry to the hosted element, 
private void Forml_Resize(object sender^ EventArgs e) 

{ 

this.OnRegionChange(elemFlost^ "Region''^ null); 

} 



' The AddRegionMapping method assigns a custom 
' mapping for the Region property. 

Private Sub AddRegionMappingO 

elemHost.PropertyMap.Add( _ 

"Region"j _ 

New PropertyTranslator(AddressOf OnRegionChange)) 

End Sub 


' The OnRegionChange method assigns an EllipseGeometry to 
' the hosted element's Clip property. 

Private Sub OnRegionChange( _ 

ByVal h As Object^ _ 

ByVal propertyName As Strings _ 

ByVal value As Object) 

Dim host As ElementHost = h 

Dim wpfButton As System.Windows.Controls.Button = host.Child 

wpfButton.Clip = New EllipseGeometry(New Rect( _ 

0 . _ 

0 . _ 

wpfButton.ActualWidthj _ 
wpfButton.ActualHeight)) 

End Sub 


' The Eorml_Resize method handles the form's Resize event. 

' It calls the OnRegionChange method explicitly to 
' assign a new clipping geometry to the hosted element. 

Private Sub Forml_Resize( _ 

ByVal sender As Object, _ 

ByVal e As EventArgs) Handles MyBase.Resize 

If elemHost IsNot Nothing Then 

Me.OnRegionChange(elemHost, "Region", Nothing) 

End If 

End Sub 

The AddRegionMapping method adds a new mapping for the Region property. 

The OnRegionChange method transiates the Region property to the WPF Ciip property. 

The Formi_Resize method handies the form's Resize event and sizes the ciipping region to fit the hosted 
eiement. 

Removing a Default Property Mapping 

Remove a defauit property mapping by caiiing the Remove method on the EiementHost controi's PropertyMap. 

To remove a default property mapping 

• Copy the foiiowing code into the definition for the Formi ciass. 







// The RemoveCunsorMapping method deletes the default 
// mapping for the Cursor property, 
private void RemoveCursorMappingO 
{ 

elemHost.PropertyMap.Remove("Cursor"); 

} 


' The RemoveCursorMapping method deletes the default 
' mapping for the Cursor property. 

Private Sub RemoveCursorMappingO 

elemHost.PropertyMap.Remove("Cursor") 

End Sub 

The RemoveCursorMapping method deletes the default mapping for the Cursor property. 

Extending a Default Property Mapping 

You can use a default property mapping and also extend it with your own mapping. 

To extend a default property mapping 

• Copy the following code into the definition for the Formi class. 

// The ExtendBackColorMapping method adds a property 
// translator if a mapping already exists, 
private void ExtendBackColorMapping() 

{ 

if (elemHost.PropertyMap["BackColor"] != null) 

{ 

elemHost.PropertyMap["BackColor"] += 

new PropertyTranslator(OnBackColorChange); 

} 

} 

// The OnBackColorChange method assigns a specific image 
// to the hosted element's Background property. 

private void OnBackColorChange(object h. String propertyNamej object value) 

{ 

ElementHost host = h as ElementHost; 

System.Windows.Controls.Button wpfButton = 

host.Child as System.Windows.Controls.Buttonj 

ImageBrush b = new ImageBrush(new Bitmaplmage( 

new Uri(@"file:///C:\WINDOWS\Santa Fe Stucco.bmp"))); 
wpfButton.Background = b; 

} 






' The ExtendBackColorMapping method adds a property 
' translator if a mapping already exists. 

Private Sub ExtendBackColorMappingO 

If elemElost.PropertyMapC'BackColor") IsNot Nothing Then 

elemHost.PropertyMapC'BackColor") = PropertyTranslator.Combine( 
elemHost.PropertyMap("BackColor "), _ 
PropertyTranslator.CreateDelegate( _ 
GetType(PropertyTranslator)j _ 

Me, _ 

"OnBackColorChange")) 

End If 

End Sub 


' The OnBackColorChange method assigns a specific image 
' to the hosted element's Background property. 

Private Sub OnBackColorChange( _ 

ByVal h As Object, _ 

ByVal propertyName As String, _ 

ByVal value As Object) 

Dim host As ElementElost = h 

Dim wpfButton As System.Windows.Controls.Button = host.Child 
Dim b As New ImageBrush(New Bitmaplmage( _ 

New Uri("file:///C:\WINDOWS\Santa Fe Stucco.bmp"))) 
wpfButton.Background = b 

End Sub 

The ExtendBackColorMapping method adds a custom property translator to the existing BackColor property 
mapping. 

The OnBackColorChange method assigns a specific image to the hosted control's Background property. The 
OnBackColorChange method is called after the default property mapping is applied. 

Initialize your property mappings 

1. Copy the following code into the definition for the Formi class. 







private void Forml_Load(object sendetj EventArgs e) 

{ 

// Create the ElementHost control. 
elemHost = new ElementHost(); 
elemHost.Dock = DockStyle.Fill; 
this.Controls. Add(elemFlost); 

// Create a Windows Presentation Foundation Button element 
// and assign it as the ElementHost control's child. 

System.Windows.Controls.Button wpfButton = new System.Windows.Controls.Button(); 
wpfButton.Content = "Windows Presentation Foundation Button"; 
elemHost.Child = wpfButton; 

// Map the Margin property, 
this.AddMarginMapping(); 

// Remove the mapping for the Cursor property, 
this.RemoveCursorMappingC); 

// Add a mapping for the Region property, 
this.AddRegionMapping(); 

// Add another mapping for the BackColor property, 
this.ExtendBackColorMapping(); 

// Cause the OnMarginChange delegate to he called. 
elemHost.Margin = new Padding(23j 23j 23j 23); 

// Cause the OnRegionChange delegate to he called. 
elemHost.Region = new Region(); 

// Cause the OnBackColorChange delegate to he called. 
elemHost.BackColor = System.Drawing.Color.AliceBlue; 



Private Sub Fortnl_Load( _ 

ByVal sender As Object^ _ 

ByVal e As EventArgs) Handles MyBase.Load 

' Create the ElementHost control. 
elemHost = IMew ElementHost() 
elemHost.Dock = DockStyle.Fill 
Me.Controls.Add(elemHost) 

' Create a Windows Presentation Foundation Button element 
' and assign it as the ElementHost control's child. 

Dim wpfButton As New System.Windows.Controls.Button() 

wpfButton.Content = "Windows Presentation Foundation Button" 

elemHost.Child = wpfButton 

' Map the Margin property. 

Me.AddMarginMapping() 

' Remove the mapping for the Cursor property. 

Me. RemoveCursorMappingO 

' Add a mapping for the Region property. 

Me.AddRegionMapping() 

' Add another mapping for the BackColor property. 

Me.ExtendBackColorMapping() 

' Cause the OnMarginChange delegate to be called. 
elemHost.Margin = New Padding(23^ 23 , 23 , 23 ) 

' Cause the OnRegionChange delegate to be called. 
elemHost.Region = New [Region]() 

' Cause the OnBackColorChange delegate to be called. 
elemHost.BackColor = System.Drawing.Color.AliceBlue 

End Sub 

The Formi_Load method handles the Load event and performs the following initialization. 

• Creates a WPF Button element. 

• Calls the methods you defined earlier in the walkthrough to set up the property mappings. 

• Assigns initial values to the mapped properties. 

2. Press F5 to build and run the application. 

See also 

• ElementHost.PropertyMap 

• WindowsFormsHost.PropertyMap 

• WindowsFormsHost 

• Windows Forms and WPF Property Mapping 

• Design XAML in Visual Studio 

• Walkthrough: Hosting a WPF Composite Control in Windows Forms 




Walkthrough; Mapping Properties Using the 
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This walkthrough shows you how to use the PropertyMap property to map WPF properties to corresponding 
properties on a hosted Windows Forms control. 

Tasks illustrated in this walkthrough include: 

• Creating the project. 

• Defining the application layout. 

• Defining a new property mapping. 

• Removing a default property mapping. 

• Replacing a default property mapping. 

• Extending a default property mapping. 

For a complete code listing of the tasks illustrated in this walkthrough, see Mapping Properties Using the 
WindowsFormsHost Element Sample. 

When you are finished, you will be able to map WPF properties to corresponding properties on a hosted Windows 
Forms control. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio 2017 

Create and set up the project 

1. Create a WPF App project named PropertyMappingWithWfhSample . 

2. In Solution Explorer, add a reference to the WindowsFormsIntegration assembly, which is named 
WindowsFormslntegration.dll. 

3. In Solution Explorer, add references to the System.Drawing and System.Windows.Forms assemblies. 

Defining the Application Layout 

The WPF-based application uses the WindowsFormsHost element to host a Windows Forms control. 

To define the application layout 

1. Open Windowl .xami in the WPF Designer. 

2. Replace the existing code with the following code. 





<Window x:Class="PropertyHappingWithWfh.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

Title="PropertyMappingWithWfh" Height="300" Width="300" 

Loaded="WindowLoaded"> 

<DockPanel Name="panell" LastChildFill="True"> 

<WindowsFormsHost Name="wfHost" DockPanel.Dock="Left" SizeChanged="Windowl_SizeChanged" 
FontSlze="20" /> 

</DockPanel> 

</Window> 


3. Open Windowl .xaml.cs in the Code Editor. 

4. At the top of the file, import the following namespaces. 

using System.Drawing; 

using System.Drawing.Drawing2D; 

using System.Windows.Forms; 

using System.Windows.Forms.Integration; 


Imports System.Drawing 

Imports System.Drawing.Drawing2D 

Imports System.Windows.Forms 

Imports System.Windows.Forms.Integration 


Defining a New Property Mapping 

The WindowsFormsHost element provides several default property mappings. You add a new property mapping 
by calling the Add method on the WindowsFormsHost element's PropertyMap. 

To define a new property mapping 

• Copy the following code into the definition for the Windowi class. 





// The AddClipMapping method adds a custom 
// mapping for the Clip property, 
private void AddClipMapping() 

{ 

wfHost.PropertyMap.Add( 

"Clip", 

new PropertyTranslator(OnClipChange)); 

} 

// The OnClipChange method assigns an elliptical clipping 
// region to the hosted control's Region property. 

private void OnClipChange(object h. String propertyName, object value) 

{ 

WindowsFormsHost host = h as WindowsFormsHost; 

System.Windows.Forms.CheckBox cb = host.Child as System.Windows.Forms.CheckBox 

if (cb != null) 

{ 

cb.Region = this.CreateClipRegion(); 

} 

} 

// The Windowl_SizeChanged method handles the window's 

// SizeChanged event. It calls the OnClipChange method explicitly 

// to assign a new clipping region to the hosted control. 

private void Windowl_SizeChanged(object sender, SizeChangedEventArgs e) 

{ 

this.OnClipChange(wfHost, "Clip", null); 

} 

// The CreateClipRegion method creates a Region from an 
// elliptical GraphicsPath. 
private Region CreateClipRegion() 

{ 

GraphicsPath path = new GraphicsPath(); 
path.StartFigure0; 

path.AddEllipse(new System.Drawing.Rectangle( 

0 , 

0 , 

(int)wfHost.ActualWidth, 

(int)wfHost.ActualHeight ) ); 

path.CloseFigureO; 

return( new Region(path) ); 

} 



' The AddClipHapping method adds a custom mapping 
' for the Clip property. 

Private Sub AddClipMappingO 

wfHost.PropertyMap.Add( _ 

"Clip", _ 

New PropertyTranslator(AddressOf OnClipChange)) 

End Sub 

' The OnClipChange method assigns an elliptical clipping 
' region to the hosted control's Region property. 

Private Sub OnClipChange( _ 

ByVal h As Object, _ 

ByVal propertyName As String, _ 

ByVal value As Object) 

Dim host As WindowsFormsHost = h 

Dim cb As System.Windows.Forms.CheckBox = host.Child 

If cb IsNot Nothing Then 

cb.Region = Me.CreateClipRegion() 

End If 

End Sub 

' The Windowl_SizeChanged method handles the window's 
' SizeChanged event. It calls the OnClipChange method explicitly 
' to assign a new clipping region to the hosted control. 

Private Sub Windowl_SizeChanged( _ 

ByVal sender As Object, _ 

ByVal e As SizeChangedEventArgs) 

Me.OnClipChange(wfHost, "Clip", Nothing) 

End Sub 

' The CreateClipRegion method creates a Region from an 
' elliptical GraphicsPath. 

Private Function CreateClipRegion() As [Region] 

Dim path As New GraphicsPath() 

path.StartFigure0 

path.AddEllipse(New System.Drawing.Rectangle( _ 

0 , _ 

0 , _ 

wfHost.ActualWidth, _ 
wfHost.ActualHeight)) 

path.CloseFigureO 

Return New [Region](path) 

End Function 

The AddClipMapping method adds a new mapping for the Clip property. 

The OnClipChange method translates the Clip property to the Windows FormsRegion property. 

The windowi_sizeChanged method handles the window's SizeChanged event and sizes the clipping region to 
fit the application window. 


Removing a Default Property Mapping 






Remove a default property mapping by calling the Remove method on the WindowsFormsHost element's 
PropertyMap. 

To remove a default property mapping 

• Copy the following code into the definition for the Windowi class. 

// The RemoveCunsorMapping method deletes the default 
// mapping for the Cursor property, 
private void RemoveCursorMappingO 
{ 

wfHost.PropertyMap.Remove("Cursor"); 

} 


' The RemoveCursorMapping method deletes the default 
' mapping for the Cursor property. 

Private Sub RemoveCursorMappingO 

wfHost.PropertyMap.Remove("Cursor") 

End Sub 

The RemoveCursorMapping method deletes the default mapping for the Cursor property. 

Replacing a Default Property Mapping 

Replace a default property mapping by removing the default mapping and calling the Add method on the 
WindowsFormsHost element's PropertyMap. 

To replace a default property mapping 

• Copy the following code into the definition for the Windowi class. 






// The ReplaceFlowDirectionMapping method replaces the 
// default mapping for the FlowDirection property, 
private void ReplaceFlowDirectionMappingO 
{ 

wfHost.PropertyMap.Remove("FlowDirection")j 

wfHost.PropertyMap.Add( 

"FlowDirection"j 

new PropertyTranslator(OnFlowDirectionChange))j 

} 

// The OnFlowDirectionChange method translates a 
// Windows Presentation Foundation FlowDirection value 
// to a Windows Forms RightToLeft value and assigns 
// the result to the hosted control's RightToLeft property. 

private void OnFlowDirectionChange(object h. String propertyNamej object value) 

{ 

WindowsFormsHost host = h as WindowsFormsHost; 

System.Windows.FlowDirection fd = (System.Windows.FlowDirection)value; 

System.Windows.Forms.CheckBox cb = host.Child as System.Windows.Forms.CheckBox 

cb.RightToLeft = (fd == System.Windows.FlowDirection.RightToLeft ) ? 
RightToLeft.Yes : RightToLeft.No; 

} 

// The cb_CheckedChanged method handles the hosted control's 
// CheckedChanged event. If the Checked property is true^ 

// the flow direction is set to RightToLeft, otherwise it is 
// set to LeftToRight. 

private void cb_CheckedChanged(object sender, EventArgs e) 

{ 

System.Windows.Forms.CheckBox cb = sender as System.Windows.Forms.CheckBox; 

wfHost.FlowDirection = ( cb.CheckState == CheckState.Checked ) ? 
System.Windows.FlowDirection.RightToLeft : 

System.Windows.FlowDirection.LeftToRight; 


} 



' The ReplaceFlowDinectionMapping method replaces the 
' default mapping for the FlowDirection property. 

Private Sub ReplaceFlowDirectionMappingO 

wfHost.PropertyMap.Remove("FlowDirection") 

wfHost.PropertyMap.Add( _ 

"FlowDirection"j _ 

New PropertyTranslator(AddressOf OnFlowDirectionChange)) 

End Sub 


' The OnFlowDirectionChange method translates a 
' Windows Presentation Foundation FlowDirection value 
' to a Windows Forms RightToLeft value and assigns 
' the result to the hosted control's RightToLeft property. 

Private Sub OnFlowDirectionChange( _ 

ByVal h As Object^ _ 

ByVal propertyName As Strings _ 

ByVal value As Object) 

Dim host As WindowsFormsHost = h 

Dim fd As System.Windows.FlowDirection = _ 

CType(valuej System.Windows.FlowDirection) 

Dim cb As System.Windows.Forms.CheckBox = host.Child 

cb.RightToLeft = IIf(fd = System.Windows.FlowDirection.RightToLeftj 
RightToLeft.YeSj _ 

RightToLeft.No) 

End Sub 


' The cb_CheckedChanged method handles the hosted control's 
' CheckedChanged event. If the Checked property is true, 

' the flow direction is set to RightToLeft^ otherwise it is 
' set to LeftToRight. 

Private Sub cb_CheckedChanged( _ 

ByVal sender As Object, _ 

ByVal e As EventArgs) 

Dim cb As System.Windows.Forms.CheckBox = sender 

wfHost.FlowDirection = Ilf(cb.CheckState = CheckState.Checked, _ 

System.Windows.FlowDirection.RightToLeft, _ 

System.Windows.FlowDirection.LeftToRight) 

End Sub 

The RepiaceEiowDirectionMapping method replaces the default mapping for the FlowDirection property. 

The onEiowDirectionChange method translates the FlowDirection property to the Windows 
FormsRightToLeft property. 

The cb_checkedchanged method handles the CheckedChanged event on the CheckBox control. It assigns the 
FlowDirection property based on the value of the CheckState property 

Extending a Default Property Mapping 

You can use a default property mapping and also extend it with your own mapping. 

To extend a default property mapping 






• Copy the following code into the definition for the Windowi class. 


// The ExtendBackgroundMapping method adds a property 
// translator if a mapping already exists, 
private void ExtendBackgroundMappingO 
{ 

if (wfHost.PropertyMap["Background"] != null) 

{ 

wfHost.PropertyMap["Background"] += new PropertyTranslator(OnBackgroundChange)j 

} 

} 

// The OnBackgroundChange method assigns a specific image 
// to the hosted control's Backgroundimage property. 

private void OnBackgroundChange(object hj String propertyName, object value) 

{ 

WindowsFormsHost host = h as WindowsFormsHost; 

System.Windows.Forms.CheckBox cb = host.Child as System.Windows.Forms.CheckBoxj 
ImageBrush b = value as ImageBrush; 

if (b != null) 

{ 

cb.Backgroundimage = new System.Drawing.Bitmap(@"C:\WINDOWS\Santa Fe Stucco.bmp"); 

} 


' The ExtendBackgroundMapping method adds a property 
' translator if a mapping already exists. 

Private Sub ExtendBackgroundMappingO 

If wfHost.PropertyMapC'Background") IsNot Nothing Then 

wfHost.PropertyMapC'Background") = PropertyTranslator.Combine( _ 
wfHost.PropertyMap("Background "), _ 

PropertyTranslator.CreateDelegate( _ 

GetType(PropertyTranslator)j _ 

Me, _ 

"OnBackgroundChange")) 

End If 

End Sub 

' The OnBackgroundChange method assigns a specific image 
' to the hosted control's Backgroundimage property. 

Private Sub OnBackgroundChange(ByVal h As Object, ByVal propertyName As String, ByVal value As Object) 
Dim host As WindowsFormsHost = h 

Dim cb As System.Windows.Forms.CheckBox = host.Child 
Dim b As ImageBrush = value 

If Not (b Is Nothing) Then 

cb.Backgroundimage = New System.Drawing.Bitmap("C:\WINDOWS\Santa Fe Stucco.bmp") 

End If 

End Sub 

The ExtendBackgroundMapping method adds a custom property translator to the existing Background 
property mapping. 

The OnBackgroundChange method assigns a specific image to the hosted control's Backgroundimage 
property. The OnBackgroundChange method is called after the default property mapping is applied. 


Initializing Your Property Mappings 







Set up your property mappings by calling the previously described methods in the Loaded event handler. 


To initialize your property mappings 

1. Copy the following code into the definition for the Windowi class. 

// The WindowLoaded method handles the Loaded event. 

// It enables Windows Forms visual styles, creates 
// a Windows Forms checkbox control, and assigns the 
// control as the child of the WindowsFormsHost element. 

// This method also modifies property mappings on the 
// WindowsFormsHost element. 

private void WindowLoaded(object sender, RoutedEventArgs e) 

{ 

System.Windows.Forms.Application.EnableVisualStyles(); 

// Create a Windows Forms checkbox control and assign 
// it as the WindowsFormsHost element's child. 

System.Windows.Forms.CheckBox cb = new System.Windows.Forms.CheckBox()j 
cb.Text = "Windows Forms checkbox"; 
cb.Dock = DockStyle.Fill; 

cb.TextAlign = ContentAlignment.MiddleCenter; 
cb.CheckedChanged += new EventHandler(cb_CheckedChanged); 
wfHost.Child = cb; 

// Replace the default mapping for the FlowDirection property. 
this.ReplaceFlowDirectionMappingO; 

// Remove the mapping for the Cursor property, 
this.RemoveCursorHappingC); 

// Add the mapping for the Clip property, 
this.AddClipMapping(); 

// Add another mapping for the Background property, 
this. ExtendBackgroundMappingO; 

// Cause the OnFlowDirectionChange delegate to be called. 
wfHost. FlowDirection = System.Windows. FlowDirection. LeftToRight; 

// Cause the OnClipChange delegate to be called. 
wfHost.Clip = new RectangleGeometryO; 

// Cause the OnBackgroundChange delegate to be called. 
wfHost.Background = new ImageBrush(); 




' The WindowLoaded method handles the Loaded event. 

' It enables Windows Forms visual styles^ creates 
' a Windows Forms checkbox control, and assigns the 
' control as the child of the WindowsFormsHost element. 

' This method also modifies property mappings on the 
' WindowsFormsHost element. 

Private Sub WindowLoaded( _ 

ByVal sender As Object, _ 

ByVal e As RoutedEventArgs) 

System.Windows.Forms.Application.EnableVisualStyles() 

' Create a Windows Forms checkbox control and assign 
' it as the WindowsFormsHost element's child. 

Dim cb As New System.Windows.Forms.CheckBox() 
cb.Text = "Windows Forms checkbox" 
cb.Dock = DockStyle.Fill 

cb.TextAlign = ContentAlignment.MiddleCenter 
AddHandler cb.CheckedChanged, AddressOf cb_CheckedChanged 
wfHost.Child = cb 

' Replace the default mapping for the FlowDirection property. 

Me. ReplaceFlowDirectionMappingO 

' Remove the mapping for the Cursor property. 

Me. RemoveCursorMappingO 

' Add the mapping for the Clip property. 

Me.AddClipMapping() 

' Add another mapping for the Background property. 

Me. ExtendBackgroundMappingO 

' Cause the OnFlowDirectionChange delegate to be called, 
wfHost.FlowDirection = System.Windows.FlowDirection.LeftToRight 

' Cause the OnClipChange delegate to be called. 
wfHost.Clip = New RectangleGeometry() 

' Cause the OnBackgroundChange delegate to be called, 
wfHost.Background = New ImageBrush() 

End Sub 

The WindowLoaded method handles the Loaded event and performs the following initialization. 

• Creates a Windows FormsCheckBox control. 

• Calls the methods you defined earlier in the walkthrough to set up the property mappings. 

• Assigns initial values to the mapped properties. 

2. Press F5 to build and run the application. Click the check box to see the effect of the FlowDirection mapping. 
When you click the check box, the layout reverses its left-right orientation. 

See also 

• WindowsFormsHost.PropertyMap 

• ElementHost.PropertyMap 

• WindowsFormsHost 

• Windows Forms and WPF Property Mapping 

• Design XAML in Visual Studio 





• Walkthrough; Hosting a Windows Forms Control in WPF 


Walkthrough: Localizing a Hybrid Application 

3/20/2020 • 4 minutes to read ^ Edit Online 


This walkthrough shows you how to localize WPF elements in a Windows Forms-based hybrid application. 

Tasks illustrated in this walkthrough include: 

• Creating the Windows Forms host project. 

• Adding localizable content. 

• Enabling localization. 

• Assigning resource identifiers. 

• Using the LocBamI tool to produce a satellite assembly. 

For a complete code listing of the tasks illustrated in this walkthrough, see Localizing a Hybrid Application Sample. 
When you are finished, you will have a localized hybrid application. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio 2017 

Creating the Windows Forms Host Project 

The first step is to create the Windows Forms application project and add a WPF element with content that you will 
localize. 

To create the host project 

1. Create a WPF App project named tocaiizingWpfinWf . (File > New > Project > Visual C# or Visual Basic 
> Classic Desktop > WPF Application). 

2. Add a WPFUserControl element called simpieControi to the project. 

3. Use the ElementHost control to place a simpieControi element on the form. For more information, see 
Walkthrough: Hosting a 3D WPF Composite Control in Windows Forms. 

Adding Localizable Content 

Next, you will add a Windows Forms label control and set the WPF element's content to a localizable string. 

To add localizable content 

1. In Solution Explorer, double-click SimpieControi.xami to open it in the WPF Designer. 

2. Set the content of the Button control using the following code. 






<UserControl x:Class="LocalizingWpfInWf.SimpleControl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

<Canvas> 

<Button Content="Hello"/> 

</Canvas> 

</UserControl> 


3. In Solution Explorer, double-click Formi to open it in the Windows Forms Designer. 

4. Open the Toolbox and double-click Label to add a label control to the form. Set the value of its Text 
property to "Hello" . 

5. Press F5 to build and run the application. 

Both the SimpleControl element and the label control display the text "Hello". 

Enabling Localization 

The Windows Forms Designer provides settings for enabling localization in a satellite assembly. 

To enable localization 

1. In Solution Explorer, double-click Formi .cs to open it in the Windows Forms Designer. 

2. In the Properties window, set the value of the form's Localizable property to true . 

3. In the Properties window, set the value of the Language property to Spanish (Spain). 

4. In the Windows Forms Designer, select the label control. 

5. In the Properties window, set the value of the Text property to "Hoia" . 

A new resource file named Formi .es-ES.resx is added to the project. 

6. In Solution Explorer, right-click Formi .cs and click View Code to open it in the Code Editor. 



8. In Solution Explorer, right-click LocalizingWpfInWf and click Unload Project. 


The project name is labeled (unavailable). 

9. Right-click LocalizingWpfInWf, and click Edit LocalizingWpfInWf.csproj. 

The project file opens in the Code Editor. 

10. Copy the following line into the first PnopentyCroup in the project file. 

<UICulture>en-LIS</LIICultur'e> 











11. Save the project file and close it. 

12. In Solution Explorer, right-click LocalizingWpfInWf and click Reload Project. 

Assigning Resource Identifiers 

You can map your localizable content to resource assemblies by using resource identifiers. The MsBuild.exe 
application automatically assigns resource identifiers when you specify the updateuid option. 

To assign resource identifiers 

1. From the Start Menu, open the Developer Command Prompt for Visual Studio. 

2. Use the following command to assign resource identifiers to your localizable content. 

msbuild -t:updateuid LocalizingWpfInWf.csproj 

3. In Solution Explorer, double-click SimpleControl.xamI to open it in the Code Editor. You will see that the 
msbuild command has added the uid attribute to all the elements. This facilitates localization through the 

assignment of resource identifiers. 

<UserContnol x:Uid="LlsenControl_l" x :Class="LocalizingWpfInWf.SimpleControl" 
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

> 

<Canvas x:Uid="Canvas_l"> 

<Button x:Llid="Button_l" Content="Hello"/> 

</Canvas> 

</UserControl> 

4. Press F6 to build the solution. 

Using LocBamI to Produce a Satellite Assembly 

Your localized content is stored in a resource-only satellite assembly. Use the command-line tool LocBaml.exe to 
produce a localized assembly for your WPF content. 

To produce a satellite assembly 

1. Copy LocBaml.exe to your project's obj\Debug folder. For more information, see Localize an Application. 

2. In the Command Prompt window, use the following command to extract resource strings into a temporary 
file. 

LocBaml /parse LocalizingWpfInWf.g.en-US.resources /out:temp.csv 

3. Open the temp.csv file with Visual Studio or another text editor. Replace the string "Hello" with its Spanish 
translation, "Hoia" . 

4. Save the temp.csv file. 

5. Use the following command to generate the localized resource file. 

LocBaml /generate /trans:temp.csv LocalizingWpfInWf.g.en-US.resources /out:. /cul:es-ES 


The LocalizingWpfInWfg.es-ES.resources file is created in the obj\Debug folder. 










6. Use the following connmand to build the localized satellite assembly. 


Al.exe /out:LocalizingWpfInWf.resources.dll /culture:es-ES /embed:LocalizingWpfInWf.Forml.es- 
ES.resources /embed:LocalizingWpfInWf.g.es-ES.resources 

The LocalizingWpflnWf.resources.dll file is created in the obj\Debug folder. 

7. Copy the LocalizingWpflnWfresources.dll file to the project's bin\Debug\es-ES folder. Replace the existing 
file. 

8. Run LocalizingWpfInWfexe, which is located in your project's bin\Debug folder. Do not rebuild the 
application or the satellite assembly will be overwritten. 

The application shows the localized strings instead of the English strings. 

See also 

• ElementHost 

• WindowsFormsHost 

• Localize an Application 

• Walkthrough: Localizing Windows Forms 

• Design XAML in Visual Studio 



WPF and Win32 Interoperation 

1 /24/2020 • 10 minutes to read ^ Edit Online 


This topic provides an overview of how to interoperate WPF and Win32 code. Windows Presentation Foundation 
(WPF) provides a rich environment for creating applications. However, when you have a substantial investment in 
Win32 code, it might be more effective to reuse some of that code. 

WPF and Win32 Interoperation Basics 

There are two basic techniques for interoperation between WPF and Win32 code. 

• Host WPF content in a Win32 window. With this technique, you can use the advanced graphics capabilities 
of WPF within the framework of a standard Win32 window and application. 

• Host a Win32 window in WPF content. With this technique, you can use an existing custom Win32 control 
in the context of other WPF content, and pass data across the boundaries. 

Each of these techniques is conceptually introduced in this topic. For a more code-oriented illustration of hosting 
WPF in Win32, see Walkthrough: Hosting WPF Content in Win32. For a more code-oriented illustration of hosting 
Win32 in WPF, see Walkthrough: Hosting a Win32 Control in WPF. 

WPF Interoperation Projects 

WPF APIs are managed code, but most existing Win32 programs are written in unmanaged C+ + . You cannot call 
WPF APIs from a true unmanaged program. However, by using the /cir option with the Microsoft Visual C+ + 
compiler, you can create a mixed managed-unmanaged program where you can seamlessly mix managed and 
unmanaged API calls. 

One project-level complication is that you cannot compile Extensible Application Markup Language (XAML) files 
into a C+ + project. There are several project division techniques to compensate for this. 

• Create a C# DLL that contains all your XAML pages as a compiled assembly, and then have your C+ + 
executable include that DLL as a reference. 

• Create a C# executable for the WPF content, and have it reference a C++ DLL that contains the Win32 
content. 

• Use Load to load any XAML at run time, instead of compiling your XAML. 

• Do not use XAML at all, and write all your WPF in code, building up the element tree from Application. 

Use whatever approach works best for you. 


NOTE 

If you have not used C++/CLI before, you might notice some "new" keywords such as gcnew and nullptr in the 

interoperation code examples. These keywords supersede the older double-underscore syntax (_gc ) and provide a more 

natural syntax for managed code in C++. To learn more about the C++/CLI managed features, see Component Extensions 
for Runtime Platforms. 


How WPF Uses Hwnds 






To make the most of WPF "HWND interop", you need to understand how WPF uses HWNDs. For any FIWND, you 
cannot mix WPF rendering with DirectX rendering or GDI / GDI+ rendering. This has a number of implications. 
Primarily, in order to mix these rendering models at all, you must create an interoperation solution, and use 
designated segments of interoperation for each rendering model that you choose to use. Also, the rendering 
behavior creates an "airspace" restriction for what your interoperation solution can accomplish. The "airspace" 
concept is explained in greater detail in the topic Technology Regions Overview. 

All WPF elements on the screen are ultimately backed by a HWND. When you create a WPF Window, WPF creates 
a top-level HWND, and uses an HwndSource to put the Window and its WPF content inside the HWND. The rest 
of your WPF content in the application shares that singular HWND. An exception is menus, combo box drop 
downs, and other pop-ups. These elements create their own top-level window, which is why a WPF menu can 
potentially go past the edge of the window HWND that contains it. When you use HwndHost to put an HWND 
inside WPF, WPF informs Win32 how to position the new child HWND relative to the WPF Window HWND. 

A related concept to HWND is transparency within and between each HWND. This is also discussed in the topic 
Technology Regions Overview. 

Hosting WPF Content in a Microsoft Win32 Window 

The key to hosting a WPF on a Win32 window is the HwndSource class. This class wraps the WPF content in a 
Win32 window, so that the WPF content can be incorporated into your user interface (Ul) as a child window. The 
following approach combines the Win32 and WPF in a single application. 

1. Implement your WPF content (the content root element) as a managed class. Typically, the class inherits 
from one of the classes that can contain multiple child elements and/or used as a root element, such as 
DockPanel or Page. In subsequent steps, this class is referred to as the WPF content class, and instances of 
the class are referred to as WPF content objects. 

2. Implement a Windows application with C + +/CLI. If you are starting with an existing unmanaged C + + 
application, you can usually enable it to call managed code by changing your project settings to include the 

/cir compiler flag (the full scope of what might be necessary to support /cir compilation is not 
described in this topic). 

3. Set the threading model to Single Threaded Apartment (STA). WPF uses this threading model. 

4. Handle the WM_CREATE notification in your window procedure. 

5. Within the handler (or a function that the handler calls), do the following: 

a. Create a new HwndSource object with the parent window HWND as its parent parameter. 

b. Create an instance of your WPF content class. 

c. Assign a reference to the WPF content object to the HwndSource object RootVisual property. 

d. The HwndSource object Handle property contains the window handle (HWND). To get an HWND 
that you can use in the unmanaged part of your application, cast Handle.ToPointer() to an HWND. 

6. Implement a managed class that contains a static field that holds a reference to your WPF content object. 

This class allows you to get a reference to the WPF content object from your Win32 code, but more 
importantly it prevents your HwndSource from being inadvertently garbage collected. 

7. Receive notifications from the WPF content object by attaching a handler to one or more of the WPF 
content object events. 

8. Communicate with the WPF content object by using the reference that you stored in the static field to set 
properties, call methods, etc. 





NOTE 

You can do some or all of the WPF content class definition for Step One in XAML using the default partial class of the 
content class, if you produce a separate assembly and then reference it. Although you typically include an Application 
object as part of compiling the XAML into an assembly, you do not end up using that Application as part of the 
interoperation, you Just use one or more of the root classes for XAML files referred to by the application and reference their 
partial classes. The remainder of the procedure is essentially similar to that outlined above. 

Each of these steps is illustrated through code in the topic Walkthrough: Hosting WPF Content in Win32. 


Hosting a Microsoft Win32 Window in WPF 

The key to hosting a Win32 window within other WPF content is the HwndHost class. This class wraps the 
window in a WPF element which can be added to a WPF element tree. HwndFiost also supports APIs that allow 
you to do such tasks as process messages for the hosted window. The basic procedure is: 

1. Create an element tree for a WPF application (can be through code or markup). Find an appropriate and 
permissible point in the element tree where the HwndHost implementation can be added as a child 
element. In the remainder of these steps, this element is referred to as the reserving element. 

2. Derive from HwndHost to create an object that holds your Win32 content. 

3. In that host class, override the HwndHost method BuildWindowCore. Return the HWND of the hosted 
window. You might want to wrap the actual control(s) as a child window of the returned window; wrapping 
the controls in a host window provides a simple way for your WPF content to receive notifications from 
the controls. This technique helps correct for some Win32 issues regarding message handling at the 
hosted control boundary. 

4. Override the HwndHost methods DestroyWindowCore and WndProc. The intention here is to process 
cleanup and remove references to the hosted content, particularly if you created references to unmanaged 
objects. 

5. In your code-behind file, create an instance of the control hosting class and make it a child of the reserving 
element. Typically you would use an event handler such as Loaded, or use the partial class constructor. But 
you could also add the interoperation content through a runtime behavior. 

6. Process selected window messages, such as control notifications. There are two approaches. Both provide 
identical access to the message stream, so your choice is largely a matter of programming convenience. 

• Implement message processing for all messages (not just shutdown messages) in your override of 
the HwndHost method WndProc. 

• Have the hosting WPF element process the messages by handling the MessageHook event. This 
event is raised for every message that is sent to the main window procedure of the hosted window. 

• You cannot process messages from windows that are out of process using WndProc. 

7. Communicate with the hosted window by using platform invoke to call the unmanaged sendMessage 
function. 

Following these steps creates an application that works with mouse input. You can add tabbing support for your 
hosted window by implementing the IKeyboardInputSink interface. 

Each of these steps is illustrated through code in the topic Walkthrough: Hosting a Win32 Control in WPF. 

Hwnds Inside WPF 

You can think of HwndHost as a special control. (Technically, HwndHost is a FrameworkElement derived class, not 




a Control derived class, but it can be considered a control for purposes of interoperation.) HwndHost abstracts the 
underlying Win32 nature of the hosted content such that the remainder of WPF considers the hosted content to 
be another control-like object, which should render and process input. HwndHost generally behaves like any 
other WPF FrameworkElement, although there are some important differences around output (drawing and 
graphics) and input (mouse and keyboard) based on limitations of what the underlying HWNDs can support. 

Notable Differences in Output Behavior 

• FrameworkElement, which is the HwndHost base class, has quite a few properties that imply changes to 
the Ul. These include properties such as FrameworkElement.FlowDirection, which changes the layout of 
elements within that element as a parent. However, most of these properties are not mapped to possible 
Win32 equivalents, even if such equivalents might exist. Too many of these properties and their meanings 
are too rendering-technology specific for mappings to be practical. Therefore, setting properties such as 
FlowDirection on HwndHost has no effect. 

• HwndHost cannot be rotated, scaled, skewed, or otherwise affected by a Transform. 

• HwndHost does not support the Opacity property (alpha blending). If content inside the HwndHost 
performs System.Drawing operations that include alpha information, that is itself not a violation, but the 
HwndHost as a whole only supports Opacity = 1.0 (100%). 

• HwndHost will appear on top of other WPF elements in the same top-level window. However, a ToolTip or 
ContextMenu generated menu is a separate top-level window, and so will behave correctly with HwndHost. 

• HwndHost does not respect the clipping region of its parent UlElement. This is potentially an issue if you 
attempt to put an HwndHost class inside a scrolling region or Canvas. 

Notable Differences in Input Behavior 

• In general, while input devices are scoped within the HwndHost hosted Win32 region, input events go 
directly to Win32. 

• While the mouse is over the HwndHost, your application does not receive WPF mouse events, and the 
value of the WPF property IsMouseOver will be false . 

• While the HwndHost has keyboard focus, your application will not receive WPF keyboard events and the 
value of the WPF property IsKeyboardFocusWithin will be false . 

• When focus is within the HwndHost and changes to another control inside the HwndHost, your application 
will not receive the WPF events GotFocus or LostFocus. 

• Related stylus properties and events are analogous, and do not report information while the stylus is over 
HwndHost. 

Tabbing, Mnemonics, and Accelerators 

The IKeyboardInputSink and IKeyboardInputSite interfaces allow you to create a seamless keyboard experience 
for mixed WPF and Win32 applications: 

• Tabbing between Win32 and WPF components 

• Mnemonics and accelerators that work both when focus is within a Win32 component and when it is 
within a WPF component. 

The HwndHost and HwndSource classes both provide implementations of IKeyboardInputSink, but they may not 
handle all the input messages that you want for more advanced scenarios. Override the appropriate methods to 
get the keyboard behavior you want. 

The interfaces only provide support for what happens on the transition between the WPF and Win32 regions. 
Within the Win32 region, tabbing behavior is entirely controlled by the Win32 implemented logic for tabbing, if 




any. 


See also 

• HwndHost 

• HwndSource 

• System.Windows.Interop 

• Walkthrough: Hosting a Win32 Control in WPF 

• Walkthrough: Hosting WPF Content in Win32 


Technology Regions Overview 
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If multiple presentation technologies are used in an application, such as WPF, Win32, or DirectX, they must share 
the rendering areas within a common top-level window. This topic describes issues that might influence the 
presentation and input for your WPF interoperation application. 

Regions 

Within a top-level window, you can conceptualize that each HWND that comprises one of the technologies of an 
interoperation application has its own region (also called "airspace"). Each pixel within the window belongs to 
exactly one HWND, which constitutes the region of that HWND. (Strictly speaking, there is more than one WPF 
region if there is more than one WPF HWND, but for purposes of this discussion, you can assume there is only 
one). The region implies that all layers or other windows that attempt to render above that pixel during application 
lifetime must be part of the same render-level technology. Attempting to render WPF pixels over Win32 leads to 
undesirable results, and is disallowed as much as possible through the interoperation APIs. 

Region Examples 

The following illustration shows an application that mixes Win32, DirectX, and WPF. Each technology uses its own 
separate, non-overlapping set of pixels, and there are no region issues. 
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Suppose that this application uses the mouse pointer position to create an animation that attempts to render over 
any of these three regions. No matter which technology was responsible for the animation itself, that technology 
would violate the region of the other two. The following illustration shows an attempt to render a WPF circle over a 
Win32 region. 
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Another violation is if you try to use transparency/alpha blending between different technologies. In the following 
illustration, the WPF box violates the Win32 and DirectX regions. Because pixels in that WPF box are semi¬ 
transparent, they would have to be owned jointly by both DirectX and WPF, which is not possible. So this is another 
violation and cannot be built. 















The previous three examples used rectangular regions, but different shapes are possible. For example, a region can 
have a hole. The following illustration shows a Win32 region with a rectangular hole this is the size of the WPF and 
DirectX regions combined. 
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Regions can also be completely nonrectangular, or any shape describable by a Win32 HRGN (region). 
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Transparency and Top-Level Windows 

The window manager in Windows only really processes Win32 HWNDs. Therefore, every WPF Window is an 
FIWND. The Window FIWND must abide by the general rules for any HWND. Within that HWND, WPF code can do 
whatever the overall WPF APIs support. But for interactions with other HWNDs on the desktop, WPF must abide by 
Win32 processing and rendering rules. WPF supports non-rectangular windows by using Win32 APIs—HRGNs for 
non-rectangular windows, and layered windows for a per-pixel alpha. 

Constant alpha and color keys are not supported. Win32 layered window capabilities vary by platform. 

Layered windows can make the entire window translucent (semi-transparent) by specifying an alpha value to apply 
to every pixel in the window. (Win32 in fact supports per-pixel alpha, but this is very difficult to use in practical 
programs because in this mode you would need to draw any child HWND yourself, including dialogs and 
dropdowns). 

WPF supports HRGNs; however, there are no managed APIs for this functionality. You can use platform invoke and 
HwndSource to call the relevant Win32 APIs. For more information, see Calling Native Functions from Managed 
Code. 

WPF layered windows have different capabilities on different operating systems. This is because WPF uses DirectX 
to render, and layered windows were primarily designed for GDI rendering, not DirectX rendering. 

• WPF supports hardware accelerated layered windows. 

• WPF does not support transparency color keys, because WPF cannot guarantee to render the exact color 
you requested, particularly when rendering is hardware-accelerated. 

See also 

• WPF and Win32 Interoperation 

• Walkthrough: Hosting a WPF Clock in Win32 

• Hosting Win32 Content in WPF 











Sharing Message Loops Between Win32 and WPF 
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This topic describes how to implement a message loop for interoperation with Windows Presentation Foundation 
(WPF), either by using existing message loop exposure in Dispatcher or by creating a separate message loop on the 
Win32 side of your interoperation code. 

ComponentDispatcher and the Message Loop 

A normal scenario for interoperation and keyboard event support is to implement IKeyboardInputSink, or to 
subclass from classes that already implement IKeyboardInputSink, such as HwndSource or HwndHost. However, 
keyboard sink support does not address all possible message loop needs you might have when sending and 
receiving messages across your interoperation boundaries. To help formalize an application message loop 
architecture, Windows Presentation Foundation (WPF) provides the ComponentDispatcher class, which defines a 
simple protocol for a message loop to follow. 

ComponentDispatcher is a static class that exposes several members. The scope of each method is implicitly tied to 
the calling thread. A message loop must call some of those APIs at critical times (as defined in the next section). 

ComponentDispatcher provides events that other components (such as the keyboard sink) can listen for. The 
Dispatcher class calls all the appropriate ComponentDispatcher methods in an appropriate sequence. If you are 
implementing your own message loop, your code is responsible for calling ComponentDispatcher methods in a 
similar fashion. 

Calling ComponentDispatcher methods on a thread will only invoke event handlers that were registered on that 
thread. 

Writing Message Loops 

The following is a checklist of ComponentDispatcher members you will use if you write your own message loop: 

• PushModal; your message loop should call this to indicate that the thread is modal. 

• PopModahyour message loop should call this to indicate that the thread has reverted to nonmodal. 

• Raiseldle; your message loop should call this to indicate that ComponentDispatcher should raise the 
Threadidle event. ComponentDispatcher will not raise Threadidle if IsThreadModal is true , but message 
loops may choose to call Raiseldle even if ComponentDispatcher cannot respond to it while in modal state. 

• RaiseThreadMessage; your message loop should call this to indicate that a new message is available. The 
return value indicates whether a listener to a ComponentDispatcher event handled the message. If 
RaiseThreadMessage returns true (handled), the dispatcher should do nothing further with the message. If 
the return value is false , the dispatcher is expected to call the Win32 function TransiateMessage , then call 

DispatchMessage . 

Using ComponentDispatcher and Existing Message Handling 

The following is a checklist of ComponentDispatcher members you will use if you rely on the inherent WPF 
message loop. 

• IsThreadModal: returns whether the application has gone modal (e.g., a modal message loop has been 
pushed). ComponentDispatcher can track this state because the class maintains a count of PushModal and 








PopModal calls from the message loop. 

• ThreadFilterMessage and ThreadPreprocessMessage events follow the standard rules for delegate 
invocations. Delegates are invoked in an unspecified order, and all delegates are invoked even if the first one 
marks the message as handled. 

• Threadidle: indicates an appropriate and efficient time to do idle processing (there are no other pending 
messages for the thread). Threadidle will not be raised if the thread is modal. 

• ThreadFilterMessage: raised for all messages that the message pump processes. 

• ThreadPreprocessMessage: raised for all messages that were not handled during ThreadFilterMessage. 

A message is considered handled if after the ThreadFilterMessage event or ThreadPreprocessMessage event, the 
handled parameter passed by reference in event data is true . Event handlers should ignore the message if 
handled is true , because that means the different handler handled the message first. Event handlers to both 
events may modify the message. The dispatcher should dispatch the modified message and not the original 
unchanged message. ThreadPreprocessMessage is delivered to all listeners, but the architectural intention is that 
only the top-level window containing the HWND at which the messages targeted should invoke code in response 
to the message. 

How HwndSource Treats ComponentDispatcher Events 

If the HwndSource is a top-level window (no parent HWND), it will register with ComponentDispatcher. If 
ThreadPreprocessMessage is raised, and if the message is intended for the HwndSource or child windows, 
HwndSource calls its IKeyboardInputSink.TranslateAccelerator, TranslateChar, OnMnemonic keyboard sink 
sequence. 

If the HwndSource is not a top-level window (has a parent HWND), there will be no handling. Only the top level 
window is expected to do the handling, and there is expected to be a top level window with keyboard sink support 
as part of any interoperation scenario. 

If WndProc on an HwndSource is called without an appropriate keyboard sink method being called first, your 
application will receive the higher level keyboard events such as KeyDown. However, no keyboard sink methods will 
be called, which circumvents desirable keyboard input model features such as access key support. This might 
happen because the message loop did not properly notify the relevant thread on the ComponentDispatcher, or 
because the parent HWND did not invoke the proper keyboard sink responses. 

A message that goes to the keyboard sink might not be sent to the HWND if you added hooks for that message by 
using the AddHook method. The message might have been handled at the message pump level directly and not 
submitted to the oispatchMessage function. 

See also 

• ComponentDispatcher 

• IKeyboardInputSink 

• WPF and Win32 Interoperation 

• Threading Model 

• Input Overview 
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Prerequisites 

See WPF and Win32 Interoperation. 

A Walkthrough of Win32 Inside Windows Presentation Framework 
(HwndHost) 

To reuse Win32 content inside WPF applications, use HwndHost, which is a control that makes HWNDs look like 
WPF content. Like HwndSource, HwndHost is straightforward to use: derive from HwndHost and implement 
BuiidWindowCone and DestroyWindowCore methods, then instantiate your HwndHost derived class and place it inside 
your WPF application. 

If your Win32 logic is already packaged as a control, then your BuiidWindowCore implementation is little more than 
a call to createWindow . For example, to create a Win32 LISTBOX control in C+ + : 

virtual HandleRef BuildWindowCore(HandleRef hwndParent) override { 

HWND handle = CreateWindowEx(0, L"LISTB0X", 

L"this is a Win32 listbox", 

WS_CHILD I WS_VISIBLE | LBS_NOTIFY 
I WS_VSCROLL I WS_B0RDER, 

0, 0, // X, y 

30, 70, // height, width 

(HWND) hwndParent.Handle.ToPointerO, // parent hwnd 
0, // hmenu 
0, // hinstance 
0); // Iparam 

return HandleRef(this, IntPtr(handle)); 

} 

virtual void DestroyWindowCore(HandleRef hwnd) override { 

// HwndHost will dispose the hwnd for us 

} 


But suppose the Win32 code is not quite so self-contained? If so, you can create a Win32 dialog box and embed its 
contents into a larger WPF application. The sample shows this in Visual Studio and C++, although it is also possible 
to do this in a different language or at the command line. 

Start with a simple dialog, which is compiled into a C + + DLL project. 

Next, introduce the dialog into the larger WPF application: 

• Compile the DLL as managed ( /cir ) 

• Turn the dialog into a control 

• Define the derived class of HwndHost with BuildWindowCore and DestroyWindowCore methods 

• Override TransiateAcceierator method to handle dialog keys 

• Override Tabinto method to support tabbing 

• Override onMnemonic method to support mnemonics 














• Instantiate the HwndHost subclass and put it under the right WPF element 


Turn the Dialog into a Control 

You can turn a dialog box into a child HWND using the WS_CHILD and DS_CONTROL styles. Go into the resource 
file (.re) where the dialog is defined, and find the beginning of the definition of the dialog: 


IDD_DIAL0G1 DIALOGEX 0, 0, 303, 121 




STYLE DS_SETFONT | DS_MODALFRAME | DS_FIXEDSYS 

1 WS_POPUP 

1 WS_CAPTION 

1 WS_SYSMENU 


Change the second line to: 


STYLE DS_SETFONT 

1 WS_CHILD 

1 WS_BORDER 

1 DS_CONTROL 






This action does not fully package it into a self-contained control; you still need to call isDiaiogMessage() so Win32 
can process certain messages, but the control change does provide a straightforward way of putting those controls 
inside another HWND. 


Subclass HwndHost 


Import the following namespaces: 



public nef class MyHwndHost : public HwndHost, IKeyboardInputSink { 
private: 

HWND dialog; 

protected: 

virtual HandleRef BuildWindowCore(HandleRef hwndParent) override { 

InitializeGlobalsO; 

dialog = CreateDialog(hInstance, 

MAKEINTRES0URCE(IDD_DIAL0G1), 

(HWND) hwndParent.Handle.ToPointer(), 

(DLGPROC) About); 

return HandleRef(this, IntPtr(dialog)); 

} 

virtual void DestroyWindowCore(HandleRef hwnd) override { 

// hwnd will be disposed for us 

} 

Here you use the createDiaiog to create the dialog box that is really a control. Since this is one of the first methods 
called inside the DLL, you should also do some standard Win32 initialization by calling a function you will define 
later, called InitializeGlobalsO • 











bool initialized = false; 

void InitializeGlobalsO { 
if (initialized) return; 
initialized = true; 

// TODO: Place code here. 

MSG msg; 

HACCEL hAccelTable; 

// Initialize global strings 

LoadString(hInstance, IDS_APP_TITLE, szTitle, MAX_LOADSTRING); 
LoadString(hInstance, IDC_TYPICALWIN32DIAL0G, szWindowClass, MAX_LOADSTRING); 
MyRegisterClass(hlnstance); 


Override TranslateAccelerator Method to Handle Dialog Keys 

If you ran this sample now, you would get a dialog control that displays, but it would ignore all of the keyboard 
processing that makes a dialog box a functional dialog box. You should now override the TranslateAccelerator 
implementation (which comes from iKeyboardinputsink , an interface that HwndHost implements). This method 
gets called when the application receives WM_KEYDOWN and WM_SYSKEYDOWN. 





#undef TranslateAccelerator 


virtual bool TranslateAccelerator(System::Windows:rlnterop::MSG% msgj 
ModifierKeys modifiers) override 

{ 

::MSG m = ConvertMessage(msg); 

// Win32's IsDialogMessageO will handle most of our tabbingj but doesn't know 
// what to do when it reaches the last tab stop 
if (m.message == WM_KEYDOWN && m.wParam == VK_TAB) { 

HWND firstTabStop = GetDlgItem(dialog, IDC_EDIT1); 

HWND lastTabStop = GetDlgItem(dialog, IDCANCEL); 

TraversalRequest'' request = nullptr; 

if (GetKeyState(\/K_SHIFT) && GetFocus() == firstTabStop) { 

// this code should workj but there's a bug with interop shift-tab in current builds 
request = gcnew TraversalRequest(FocusNavigationDirection::Last)j 

} 

else if (!GetKeyState(\/K_SHIFT) && GetFocus() == lastTabStop) { 

request = gcnew TraversalRequest(FocusNavigationDirection::Next)j 

} 

if (request != nullptr) 

return ((IKeyboardInputSink'') this)->KeyboardInputSite->OnNoMoreTabStops(request); 


// Only call IsDialogHessage for keys it will do something with. 

if (msg.message == WM_SYSKEYDOWN || msg.message == WM_KEYDOWN) { 
switch (m.wParam) { 
case VK_TAB: 
case VK_LEFT: 
case VK_UP: 
case VK_RIGHT: 
case VK_DOWN: 
case VK_EXECUTE: 
case VK_RETURN: 
case VK_ESCAPE: 
case VK_CANCEL: 

IsDialogMessage(dialogj &m); 

// IsDialogMessage should be called ProcessDialogMessage -- 
// it processes messages without ever really telling you 
// if it handled a specific message or not 
return true; 

} 

} 

return false; // not a key we handled 

} 


This is a lot of code in one piece, so it could use some more detailed explanations. First, the code using Cf f and 
Cf f macros; you need to be aware that there is already a macro named TranslateAccelerator , which is defined in 
winuser.h: 


#define TranslateAccelerator TranslateAcceleratorW 

So make sure to define a TranslateAccelerator method and not a TranslateAcceleratorW method. 

Similarly, there is both the unmanaged winuser.h MSG and the managed Microsoft: :Win32: :msg struct. You can 
disambiguate between the two using the Cff :: operator. 









virtual bool TranslateAccelerator(System::Windows:rlnterop::MSG% msgj 
ModifierKeys modifiers) override 

{ 

::MSG m = ConvertMessage(msg); 

} 


Both MSGs have the same data, but sometimes it is easier to work with the unmanaged definition, so in this sample 
you can define the obvious conversion routine: 

::MSG ConvertMessage(System:iWindows::Interop::MSG% msg) { 

::MSG m; 

m.hwnd = (HWND) msg.hwnd.ToPointer(); 
m.lParam = (LPARAH) msg.lParam.ToPointer()j 
m.message = msg.message; 

m.wParam = (WPARAM) msg.wParam.ToPointer(); 

m.time = msg.time; 

POINT pt; 
pt.x = msg.pt_x; 
pt.y = msg.pt_y; 
m.pt = pt; 

return m; 

} 

Back to TranslateAccelerator . The basic principle is to Call the Win32 function IsDialogMessage to do as much 
work as possible, but IsDialogMessage does not have access to anything outside the dialog. As a user tab around 
the dialog, when tabbing runs past the last control in our dialog, you need to set focus to the WPF portion by 
calling IKeyboardInputSite: lOnNoMoreStops . 

// Win32's IsDialogMessageO will handle most of the tabbingj but doesn't know 
// what to do when it reaches the last tab stop 
if (m.message == WM_KEYDOWN && m.wParam == VK_TAB) { 

HWND firstTabStop = GetDlgItem(dialog, IDC_EDIT1); 

HWND lastTabStop = GetDlgItem(dialog, IDCANCEL); 

TraversalRequest^' request = nullptr; 

if (GetKeyState(VK_SHIFT) && GetFocus() == firstTabStop) { 

request = gcnew TraversalRequest(FocusNavigationDirection::Last); 

} 

else if (!GetKeyState(VK_SHIFT) && GetFocus() == lastTabStop) { { 
request = gcnew TraversalRequest(FocusNavigationDirection::Next); 

} 

if (request != nullptr) 

return ((IKeyboardInputSink'') this)->KeyboardInputSite->OnNoMoreTabStops(request); 

} 

Finally, call IsDialogMessage . But one of the responsibilities of a TranslateAccelerator method is telling WPF 
whether you handled the keystroke or not. If you did not handle it, the input event can tunnel and bubble through 
the rest of the application. Here, you will expose a quirk of keyboard messange handling and the nature of the 
input architecture in Win32. Unfortunately, IsDialogMessage does not return in any way whether it handles a 
particular keystroke. Even worse, it will call DispatchMessage() on keystrokes it should not handle! So you will have 
to reverse-engineer IsDialogMessage , and only call it for the keys you know it will handle: 










// Only call IsDialogHessage for keys it will do something with, 
if (msg.message == WM_SYSKEYDOWN || msg.message == WM_KEYDOWN) { 
switch (m.wPanam) { 
case VK_TAB: 
case VK_LEET: 
case VK_UP: 
case VK_RIGHT: 
case VK_DOWN: 
case VK_EXECUTE: 
case VK_RETURN: 
case VK_ESCAPE: 
case VK_CANCEL: 

IsDialogMessage(dialog, &m); 

// IsDialogMessage should be called ProcessDialogMessage -- 
// it processes messages without ever really telling you 
// if it handled a specific message or not 
return true; 


Override Tabinto Method to Support Tabbing 

Now that you have implemented TransiateAcceierator , a user can tab around inside the dialog box and tab out of 
it into the greater WPF application. But a user cannot tab back into the dialog box. To solve that, you override 
Tabinto : 

public: 

virtual bool TabInto(TraversalRequest'' request) override { 

if (request->PocusNavigationDirection == EocusNavigationDirection::Last) { 

HWND lastTabStop = GetDlgItem(dialogj IDCANCEL); 

SetEocus(lastTabStop); 

} 

else { 

HWND firstTabStop = GetDlgItem(dialog, IDC_EDIT1); 

SetFocus(firstTabStop); 

} 

return true; 

} 

The TraversaiRequest parameter tells you whether the tab action is a tab or shift tab. 

Override OnMnemonic Method to Support Mnemonics 

Keyboard handling is almost complete, but there is one thing missing - mnemonics do not work. If a user presses 
alt-F, focus doe not jump to the "First name:" edit box. So, you override the OnMnemonic method: 







virtual bool OnMnemonic(System::Windows::Interop::MSG% msgj ModifierKeys modifiers) override { 
::MSG m = ConvertMessage(msg); 

// If it's one of our mnemonicsj set focus to the appropriate hwnd 
if (msg.message == WM_SYSCHAR && GetKeyState(VK_MENU /*alt*/)) { 
int dialogitem = 9999; 
switch (m.wParam) { 


case 

' s' 

dialogitem 

= 

IDOK 

; break; 

case 

' c' 

dialogitem 

= 

IDCANCEL; 

areak; 

case 

■f 

dialogitem 

= 

IDC_ 

EDITl; 

break; 

case 

■1' 

dialogitem 

= 

IDC_ 

EDIT2; 

break; 

case 

■p' 

dialogitem 

= 

IDC_ 

EDITS; 

break; 

case 

' a' 

dialogitem 

= 

IDC_ 

EDITA; 

break; 

case 

' i' 

dialogitem 

= 

IDC_ 

EDITS; 

break; 

case 

■f 

dialogitem 


IDC_ 

EDITS; 

break; 

case 

' z' 

dialogitem 


IDC_ 

EDIT7; 

break; 


} 

if (dialogitem != 9999) { 

HWND hwnd = GetDlgItem(dialog, dialogitem); 

SetFocus(hwnd); 
return true; 

} 

} 

return false; // key unhandled 

}; 

Why not call isDiaiogMessage here? You have the same issue as before—you need to be able to inform WPF code 
whether your code handled the keystroke or not, and isDiaiogMessage cannot do that. There is also a second issue, 
because IsDiaiogMessage refuses to process the mnemonic if the focused HWND is not inside the dialog box. 

Instantiate the HwndHost Derived Class 

Finally, now that all the key and tab support is in place, you can put your HwndHost into the larger WPF application. 
If the main application is written in XAML, the easiest way to put it in the right place is to leave an empty Border 
element where you want to put the HwndHost. Here you create a Border named insertHwndHostHere : 

<Window x:Class="WPFApplicationl.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 

Title="Windows Presentation Framework Application" 

Loaded="Windowl_Loaded" 

> 

<StackPanel> 

<Button Content="WPF button"/> 

<Border Name="insertHwndHostHere" Height="200" Width="500"/> 

<Button Content="WPF button"/> 

</StackPanel> 

</Window> 


Then all that remains is to find a good place in code sequence to instantiate the HwndHost and connect it to the 
Border. In this example, you will put it inside the constructor for the Window derived class: 

public partial class Windowl : Window { 
public WindowlO { 

} 

void Windowl_Loaded(object senderj RoutedEventArgs e) { 

HwndHost host = new ManagedCpp.MyHwndHost(); 
insertHwndHostHere.Child = host; 

} 

} 








Which gives you: 



See also 

• WPF and Win32 Interoperation 
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Windows Presentation Foundation (WPF) provides a rich environment for creating applications. However, when 
you have a substantial investment in Win32 code, it may be more effective to reuse at least some of that code in 
your WPF application rather than rewrite it completely. WPF provides a straightforward mechanism for hosting a 
Win32 window, on a WPF page. 

This topic walks you through an application, Hosting a Win32 ListBox Control in WPF Sample, that hosts a Win32 
list box control. This general procedure can be extended to hosting any Win32 window. 

Requirements 

This topic assumes a basic familiarity with both WPF and Windows API programming. For a basic introduction to 
WPF programming, see Getting Started. For an introduction to Windows API programming, see any of the 
numerous books on the subject, in particular Programming Windowsby Charles Petzold. 

Because the sample that accompanies this topic is implemented in C#, it makes use of Platform Invocation 
Services (PInvoke) to access the Windows API. Some familiarity with PInvoke is helpful but not essential. 


NOTE 

This topic includes a number of code examples from the associated sample. However, for readability, it does not include the 
complete sample code. You can obtain or view complete code from Hosting a Win32 ListBox Control in WPF Sample. 


The Basic Procedure 

This section outlines the basic procedure for hosting a Win32 window on a WPF page. The remaining sections go 

through the details of each step. 

The basic hosting procedure is: 

1. Implement a WPF page to host the window. One technique is to create a Border element to reserve a 
section of the page for the hosted window. 

2. Implement a class to host the control that inherits from HwndHost. 

3. In that class, override the HwndHost class member BuildWindowCore. 

4. Create the hosted window as a child of the window that contains the WPF page. Although conventional 
WPF programming does not need to explicitly make use of it, the hosting page is a window with a handle 
(HWND). You receive the page HWND through the hwndParent parameter of the BuildWindowCore method. 
The hosted window should be created as a child of this HWND. 

5. Once you have created the host window, return the HWND of the hosted window. If you want to host one or 
more Win32 controls, you typically create a host window as a child of the HWND and make the controls 
children of that host window. Wrapping the controls in a host window provides a simple way for your WPF 
page to receive notifications from the controls, which deals with some particular Win32 issues with 
notifications across the HWND boundary. 

6. Handle selected messages sent to the host window, such as notifications from child controls. There are two 
ways to do this. 






• If you prefer to handle messages in your hosting class, override the WndProc method of the 
HwndHost class. 

• If you prefer to have the WPF handle the messages, handle the HwndHost class MessageHook event 
in your code-behind. This event occurs for every message that is received by the hosted window. If 
you choose this option, you must still override WndProc, but you only need a minimal 
implementation. 

7. Override the DestroyWindowCore and WndProc methods of HwndHost. You must override these methods 
to satisfy the HwndHost contract, but you may only need to provide a minimal implementation. 

8. In your code-behind file, create an instance of the control hosting class and make it a child of the Border 
element that is intended to host the window. 

9. Communicate with the hosted window by sending it Microsoft Windows messages and handling messages 
from its child windows, such as notifications sent by controls. 

Implement the Page Layout 

The layout for the WPF page that hosts the ListBox Control consists of two regions. The left side of the page hosts 
several WPF controls that provide a user interface (Ul) that allows you to manipulate the Win32 control. The upper 
right corner of the page has a square region for the hosted ListBox Control. 

The code to implement this layout is quite simple. The root element is a DockPanel that has two child elements. 

The first is a Border element that hosts the ListBox Control. It occupies a 200x200 square in the upper right corner 
of the page. The second is a StackPanel element that contains a set of WPF controls that display information and 
allow you to manipulate the ListBox Control by setting exposed interoperation properties. For each of the elements 
that are children of the StackPanel, see the reference material for the various elements used for details on what 
these elements are or what they do, these are listed in the example code below but will not be explained here (the 
basic interoperation model does not require any of them, they are provided to add some interactivity to the 
sample). 


<Window 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.micnosoft.com/winfx/2006/xaml" 
x:Class="WPF_Hosting_Win32_Contnol.HostWindow" 

Name="mainWindow" 

Loaded="On_UIReady"> 

<DockPanel Background="LightGneen"> 

<Bonder Name="ControlHostElement" 

Width="200" 

Height="200" 

HorizontalAlignment="Right" 

VerticalAlignment="Top" 

BorderBrush="LightGray" 

BorderThickness="3" 

DockPanel.Dock="Right"/> 

<StackPanel> 

<Label HorizontalAlignment="Center" 

Margin="0j10^0,0" 

FontSize="14" 

FontWeight="Bold">Control the Control</Label> 

<TextBlock Hargin="10jl0,10jl0" >Selected Text: <TextBlock Name="selectedText"/></TextBlock> 
<TextBlock Hargin="10jl0,10jl0" >Mumber of Items: <TextBlock Name="numItems"/></TextBlock> 

<Line X1="0" X2="200" 

Stroke="LightYellow" 

StrokeThickness="2" 

HorizontalAlignment="Center" 

Margin="0j 20 , 0 , 0 "/> 

<Label HorizontalAlignment="Center" 

Margin="10,10jl0,10">Append an Item to the List</Label> 

<StackPanel Orientation="Florizontal"> 

<Label HorizontalAlignment="Left" 

Margin="10jl0j10,10">Item Text</Label> 

<TextBox HorizontalAlignment="Left" 

Name="txtAppend" 

Width="200" 

Margin="10^ 10 , 10 , 10"></TextBox> 

</StackPanel> 

<Button HorizontalAlignment="Left" 

Click="AppendText" 

Width="75" 

Margin="10, 10 , 10 , 10">Append</Button> 

<Line X1="0" X2="200" 

Stroke="LightYellow" 

StrokeThickness="2" 

HorizontalAlignment="Center" 

Margin="0j20j0,0"/> 

<Label HorizontalAllgnment="Center" 

Margin="10,10jl0jl0">Delete the Selected Item</Label> 

<Button Click="DeleteText" 

Wldth="125" 

Margin="10,10,10,10" 

HorizontalAlignment="Left">Delete</Button> 

</StackPanel> 

</DockPanel> 

</Window> 


Implement a Class to Host the Microsoft Win32 Control 



The core of this sample is the class that actually hosts the control, ControlHostcs. It inherits from HwndHost. The 
constructor takes two parameters, height and width, which correspond to the height and width of the Border 
element that hosts the ListBox control. These values are used later to ensure that the size of the control matches 
the Border element. 


public class ContnolHost : HwndHost 
{ 

IntPtn hwndControl; 

IntPtn hwndHost; 

int hostHeight, hostWidth; 

public ControlHost(double height, double width) 
{ 

hostHeight = (int)height; 
hostWidth = (int)width; 

} 


Public Class ContnolHost 
Inherits HwndHost 
Private hwndControl As IntPtr 
Private hwndHost As IntPtr 
Private hostHeight, hostWidth As Integer 

Public Sub New(ByVal height As Double, ByVal width As Double) 
hostHeight = Clnt(height) 
hostWidth = Clnt(width) 

End Sub 


There is also a set of constants. These constants are largely taken from Winuser.h, and allow you to use 
conventional names when calling Win32 functions. 


internal const int 

WS_CHILD = 0x40000000, 
WS_VISIBLE = 0x10000000, 
LBS_NOTIFY = 0X00000001, 
HOST_ID = 0X00000002, 
LISTBOX_ID = 0X00000001, 
WS_VSCROLL = 0X00200000, 
WS_BORDER = 0x00800000; 


Friend Const WS_CHILD As Integer = &H40000000, WS_VISIBLE As Integer = &H10000000, LBS_NOTIFY As Integer = 
&H00000001, HOST_ID As Integer = &H00000002, LISTBOX_ID As Integer = &H00000001, WS_VSCROLL As Integer = 
&H00200000, WS_BORDER As Integer = &H00800000 


Override BuildWindowCore to Create the Microsoft Win32 Window 

You override this method to create the Win32 window that will be hosted by the page, and make the connection 
between the window and the page. Because this sample involves hosting a ListBox Control, two windows are 
created. The first is the window that is actually hosted by the WPF page. The ListBox Control is created as a child of 
that window. 

The reason for this approach is to simplify the process of receiving notifications from the control. The HwndHost 
class allows you to process messages sent to the window that it is hosting. If you host a Win32 control directly, you 
receive the messages sent to the internal message loop of the control. You can display the control and send it 
messages, but you do not receive the notifications that the control sends to its parent window. This means, among 
other things, that you have no way of detecting when the user interacts with the control. Instead, create a host 
window and make the control a child of that window. This allows you to process the messages for the host window 




including the notifications sent to it by the control. For convenience, since the host window is little more than a 
simple wrapper for the control, the package will be referred to as a ListBox control. 

Create the Host Window and ListBox Control 

You can use PInvoke to create a host window for the control by creating and registering a window class, and so on. 
However, a much simpler approach is to create a window with the predefined "static" window class. This provides 
you with the window procedure you need in order to receive notifications from the control, and requires minimal 
coding. 

The HWND of the control is exposed through a read-only property, such that the host page can use it to send 
messages to the control. 

public IntPtr hwndListBox 
{ 

get { return hwndControl; } 

} 

Public Readonly Property hwndListBox() As IntPtr 
Get 

Return hwndControl 
End Get 
End Property 

The ListBox control is created as a child of the host window. The height and width of both windows are set to the 
values passed to the constructor, discussed above. This ensures that the size of the host window and control is 
identical to the reserved area on the page. After the windows are created, the sample returns a HandleRef object 
that contains the HWND of the host window. 


protected override HandleRef BuildWindowCore(HandleRef hwndParent) 
{ 

hwndControl = IntPtr.Zero; 
hwndHost = IntPtr.Zero; 

hwndHost = CreateWindowEx(0j "static"j 

WS_CHILD I WS_VISIBLE, 

0 , 0 , 

hostWidth, hostHeight, 
hwndParent.Handle, 

(IntPtr)HOST_ID, 

IntPtr.Zero, 

0 ); 

hwndControl = CreateWindowEx(0, "listbox", 

WS_CHILD I WS_VISIBLE | LBS_NOTIFY 
I WS_VSCROLL I WS_BORDER, 

0 , 0 , 

hostWidth, hostHeight, 
hwndHost, 

(IntPtr) LISTBOX_ID, 

IntPtr.Zero, 

0 ); 

return new HandleRef(this, hwndHost); 

} 




Protected Overrides Function BuildWindowCore(ByVal hwndParent As HandleRef) As HandleRef 
hwndControl = IntPtr.Zero 
hwndHost = IntPtr.Zero 

hwndHost = CreateWindowEx(0j "static"j WS_CHILD Or WS_VISIBLE, 0j 0, hostWidthj hosthleightj 
hwndParent.ElandlOj New IntPtr(HOST_ID)^ IntPtr.Zero, 0) 

hwndControl = CreateWindowEx(0, "listbox", WS_CHILD Or WS_VISIBLE Or LBS_NOTIFY Or WS_VSCROLL Or 
WS_BORDER, 0, 0, hostWidth, hostHeight, hwndHost, New IntPtr(LISTBOX_ID), IntPtr.Zero, 0) 

Return New HandleRef(Me, hwndHost) 

End Function 


//PInvoke declarations 

[DllImport("user32.dll", EntryPoint = "CreateWindowEx", CharSet = CharSet.Unicode)] 
internal static extern IntPtr CreateWindowEx(int dwExStyle, 

string IpszClassName, 
string IpszWindowName, 
int style, 
int X, int y, 
int width, int height, 

IntPtr hwndParent, 

IntPtr hMenu, 

IntPtr hinst, 

[MarshalAs(UnmanagedType.AsAny)] object pvParam); 


'PInvoke declarations 

<DllImport("user32.dll", EntryPoint := "CreateWindowEx", CharSet := CharSet.Unicode)> 

Friend Shared Function CreateWindowEx(By\/al dwExStyle As Integer, ByVal IpszClassName As String, ByVal 
IpszWindowName As String, ByVal style As Integer, ByVal x As Integer, ByVal y As Integer, ByVal width As 
Integer, ByVal height As Integer, ByVal hwndParent As IntPtr, ByVal hMenu As IntPtr, ByVal hinst As IntPtr, 
<MarshalAs(UnmanagedType.AsAny)> ByVal pvParam As Object) As IntPtr 
End Function 


Implement DestroyWindow and WndProc 

In addition to BuildWindowCore, you must also override the WndProc and DestroyWindowCore methods of the 
HwndHost. In this example, the messages for the control are handled by the MessageHook handler, thus the 
implementation of WndProc and DestroyWindowCore is minimal. In the case of WndProc, set handled to false 
to indicate that the message was not handled and return 0. For DestroyWindowCore, simply destroy the window. 

protected override IntPtr WndProc(IntPtr hwnd, int msg, IntPtr wParam, IntPtr IParam, ref bool handled) 

{ 

handled = false; 
return IntPtr.Zero; 

} 

protected override void DestroyWindowCore(HandleRef hwnd) 

{ 

DestroyWindow(hwnd.Handle); 

} 






Protected Overrides Function WndProc(ByVal hwnd As IntPtr, ByVal msg As Integer, ByVal wParam As IntPtr, ByVal 
IParatn As IntPtr, ByRef handled As Boolean) As IntPtr 
handled = False 
Return IntPtr.Zero 
End Function 

Protected Overrides Sub DestroyWindowCore(ByVal hwnd As HandleRef) 

DestroyWindow(hwnd.Handle) 

End Sub 


[DllIniport("user32.dll", EntryPoint = "DestroyWindow", CbarSet = CbarSet.Unicode)] 
internal static extern bool DestroyWindow(IntPtr hwnd)j 


<DllImport("user32.dll", EntryPoint "DestroyWindow", CharSet := CbarSet.Unicode)> 
Eriend Shared Function DestroyWindow(ByVal hwnd As IntPtr) As Boolean 
End Eunction 


Host the Control on the Page 

To host the control on the page, you first create a new instance of the controiHost class. Pass the height and width 
of the border element that contains the control ( controiHostEiement ) to the controiHost constructor. This ensures 
that the ListBox is sized correctly. You then host the control on the page by assigning the ControiHost object to the 
Child property of the host Border. 

The sample attaches a handler to the MessageHook event of the ControiHost to receive messages from the 
control. This event is raised for every message sent to the hosted window. In this case, these are the messages sent 
to window that wraps the actual ListBox control, including notifications from the control. The sample calls 
SendMessage to obtain information from the control and modify its contents. The details of how the page 
communicates with the control are discussed in the next section. 


NOTE 

Notice that there are two PInvoke declarations for SendMessage. This is necessary because one uses the wParam parameter 
to pass a string and the other uses it to pass an integer. You need a separate declaration for each signature to ensure that 
the data is marshaled correctly. 






public partial class HostWindow : Window 

{ 

int selecteditem; 

IntPtr hwndiistBox; 

ControlHost listControl; 

Application app; 

Window myWindow; 
int itemCount; 

private void On_UIReady(object sender^ EventArgs e) 

{ 

app = System.Windows.Application.Current; 
myWindow = app.HainWindow; 

myWindow.SizeToContent = SizeToContent.WidthAndHeight; 

listControl = new ControlHost(ControlHostElement.ActualHeight, ControlHostElement.ActualWidth); 
ControlHostElement.Child = listControl; 

listControl.MessageHook += new HwndSourceHook(Controll''lsgFilter); 
hwndiistBox = listControl.hwndListBox; 
for (int i = 0; i < 15; i++) //populate listbox 
{ 

string itemText = "Item" + i.ToStringO; 

SendMessage(hwndListBoXj LB_ADDSTRINGj IntPtr.ZerOj itemText); 

} 

itemCount = SendMessage(hwndListBoXj LB_GETCOLINTj IntPtr.Zero, IntPtr.Zero); 
numItems.Text = "" + itemCount.ToStringO; 


Partial Public Class HostWindow 
Inherits Window 

Private selecteditem As Integer 
Private hwndiistBox As IntPtr 
Private listControl As ControlHost 
Private app As Application 
Private myWindow As Window 
Private itemCount As Integer 

Private Sub On_UIReady(ByVal sender As Object, ByVal e As EventArgs) 
app = System.Windows.Application.Current 
myWindow = app.HainWindow 

myWindow.SizeToContent = SizeToContent.WidthAndHeight 

listControl = New ControlHost(ControlHostElement.ActualHeight, ControlHostElement.ActualWidth) 
ControlHostElement.Child = listControl 

AddHandler listControl.MessageHook, AddressOf ControlMsgFilter 

hwndiistBox = listControl.hwndiistBox 

For i As Integer = 0 To 14 'populate listbox 

Dim itemText As String = "Item" & i.ToStringO 
SendMessage(hwndiistBox, iB_ADDSTRING, IntPtr.Zero, itemText) 

Next i 

itemCount = SendMessage(hwndiistBox, iB_GETCOilNT, IntPtr.Zero, IntPtr.Zero) 
numItems.Text = "" & itemCount.ToStringO 
End Sub 



private IntPtr ControlMsgFilter(IntPtr hwndj int msgj IntPtr wParam, IntPtr IPararrij ref bool handled) 

{ 

int textLength; 

handled = false; 
if (msg == WM_COMMAND) 

{ 

switch ((uint)wParam.ToInt32() >> 16 & 0xFFFF) //extract the HIWORD 

{ 

case LBN_SELCFIANGE : //Get the item text and display it 

selecteditem = SendMessage(listControl.hwndListBoXj LB_GETCLIRSELj IntPtr.Zero, IntPtr.Zero); 
textLength = SendMessage(listControl.hwndListBoXj LB_GETTEXTLENj IntPtr.ZerOj IntPtr.Zero); 
StringBuilder itemlext = new StringBuilder(); 

SendMessage(hwndListBoXj LB_GETTEXTj selecteditem, itemlext); 
selectedText.Text = itemlext.ToStringO; 
handled = true; 
break; 

} 

} 

return IntPtr.Zero; 

} 

internal const int 

LBN_SELCHANGE = 0X00000001, 

WM_COMMAND = 0X00000111, 

LB_GETCURSEL = 0X00000188, 

LB_GETTEXTLEN = 0X0000018A, 

LB_ADDSTRING = 0X00000180, 

LB_GETTEXT = 0X00000189, 

LB_DELETESTRING = 0X00000182, 

LB_GETCOUIMT = 0X0000018B; 

[DllImport("user32.dll", EntryPoint = "SendMessage", CharSet = CharSet.Unicode)] 
internal static extern int SendMessage(IntPtr hwnd, 

int msg, 

IntPtr wParam, 

IntPtr IParam); 

[DllImport("user32.dll", EntryPoint = "SendMessage", CharSet = CharSet.Unicode)] 
internal static extern int SendMessage(IntPtr hwnd, 

int msg, 
int wParam, 

[MarshalAs(UnmanagedType.LPWStr)] StringBuilder IParam); 

[DllImport("user32.dll", EntryPoint = "SendMessage", CharSet = CharSet.Unicode)] 
internal static extern IntPtr SendMessage(IntPtr hwnd, 

int msg, 

IntPtr wParam, 

String IParam); 



Private Function ControlMsgFilter(By\/al hwnd As IntPtTj ByVal msg As IntegeCj ByVal wParam As IntPtrj ByVal 
IParatn As IntPtr^ ByRef handled As Boolean) As IntPtr 
Dim textLength As Integer 

handled = False 

If msg = WM_COMMAND Then 

Select Case CUInt(wParam.ToInt32()) >> 16 And &HFFFF 'extract the HIWORD 
Case LBN_SELCHAIMGE 'Get the item text and display it 

selecteditem = SendMessage(listControl.hwndListBoXj LB_GETCLIRSELj IntPtr.Zero, IntPtr.Zero) 
textLength = SendMessage(listControl.hwndListBox, LB_GETTEXTLEN, IntPtr.Zero, IntPtr.Zero) 
Dim itemText As New StringBuilder() 

SendMessage(hwndListBox, LB_GETTEXT, selecteditem, itemText) 
selectedText.Text = itemText .ToStringO 
handled = True 
End Select 
End If 

Return IntPtr.Zero 
End Function 

Friend Const LBN_SELCHANGE As Integer = &H1, WM_COMMAND As Integer = &H111, LB_GETCURSEL As Integer = &H188, 
LB_GETTEXTLEN As Integer = &H18A, LB_ADDSTRING As Integer = &H180, LB_GETTEXT As Integer = &H189, 
LB_DELETESTRING As Integer = &H182, LB_GETCOUNT As Integer = &H18B 

<DllImport("user32.dll", EntryPoint:="SendMessage", CharSet:=CharSet.Unicode)> 

Friend Shared Function SendMessage(ByVal hwnd As IntPtr, ByVal msg As Integer, ByVal wParam As IntPtr, ByVal 
IParam As IntPtr) As Integer 
End Function 

<DllImport("user32.dll", EntryPoint:="SendMessage", CharSet:=CharSet.Unicode)> 

Friend Shared Function SendMessage(ByVal hwnd As IntPtr, ByVal msg As Integer, ByVal wParam As Integer, 
<MarshalAs(UnmanagedType.LPWStr)> ByVal IParam As StringBuilder) As Integer 
End Eunction 

<DllImport("user32.dll", EntryPoint:="SendMessage", CharSet:=CharSet.Unicode)> 

Eriend Shared Eunction SendMessage(ByVal hwnd As IntPtr, ByVal msg As Integer, ByVal wParam As IntPtr, ByVal 
IParam As String) As IntPtr 
End Eunction 


Implement Communication Between the Control and the Page 

You manipulate the control by sending it Windows messages. The control notifies you when the user interacts with 
it by sending notifications to its host window. The Hosting a Win32 ListBox Control in WPF sample includes a Ul 
that provides several examples of how this works: 

• Append an item to the list. 

• Delete the selected item from the list 

• Display the text of the currently selected item. 

• Display the number of items in the list. 

The user can also select an item in the list box by clicking on it, just as they would for a conventional Win32 
application. The displayed data is updated each time the user changes the state of the list box by selecting, adding, 
or appending an item. 

To append items, send the list box an lb_addstring message. To delete items, send lb_getcursel to get the index 
of the current selection and then lb_deletestring to delete the item. The sample also sends lb_getcount , and 
uses the returned value to update the display that shows the number of items. Both these instances of 
sendMessage use one of the PInvoke declarations discussed in the previous section. 








private void AppendText(object sendetj EventArgs args) 

{ 

if (!string.IsNullOrEmpty(txtAppend.Text)) 

{ 

SendMessage(hwndListBoXj LB_ADDSTRINGj IntPtr.ZerOj txtAppend.Text); 

} 

itemCount = SendMessage(hwndListBoXj LB_GETCOLINTj IntPtr.ZerOj IntPtr.Zero); 
numItems.Text = "" + itemCount.ToStringO; 

} 

private void DeleteText(object sender^ EventArgs args) 

{ 

selecteditem = SendMessage(listControl.hwndListBoXj LB_GETCURSELj IntPtr.Zero, IntPtr.Zero); 
if (selecteditem != -1) //check for selected item 
{ 

SendMessage(hwndListBox, LB_DELETESTRING, (IntPtr)selectedltem, IntPtr.Zero); 

} 

itemCount = SendMessage(hwndListBox, LB_GETCOUNT, IntPtr.Zero, IntPtr.Zero); 
numItems.Text = "" + itemCount.ToStringO; 


Private Sub AppendText(ByVal sender As Object, ByVal args As EventArgs) 

If txtAppend.Text <> String.Empty Then 

SendMessage(hwndListBox, LB_ADDSTRING, IntPtr.Zero, txtAppend.Text) 

End If 

itemCount = SendMessage(hwndListBox, LB_GETCOLINT, IntPtr.Zero, IntPtr.Zero) 
numItems.Text = "" & itemCount.ToStringO 
End Sub 

Private Sub DeleteText(ByVal sender As Object, ByVal args As EventArgs) 

selecteditem = SendMessage(listControl.hwndListBox, LB_GETCLIRSEL, IntPtr.Zero, IntPtr.Zero) 
If selecteditem <> -1 Then 'check for selected item 

SendMessage(hwndListBox, LB_DELETESTRING, New IntPtr(selectedltem), IntPtr.Zero) 

End If 

itemCount = SendMessage(hwndListBox, LB_GETCOLINT, IntPtr.Zero, IntPtr.Zero) 
numItems.Text = "" & itemCount.ToStringO 
End Sub 


When the user selects an item or changes their selection, the control notifies the host window by sending it a 
WM_coMMAND message, which raises the MessageHook event for the page. The handler receives the same 
information as the main window procedure of the host window. It also passes a reference to a Boolean value, 
handled . You set handled to true to indicate that you have handled the message and no further processing is 
needed. 

WM_coMMAND is Sent for a variety of reasons, so you must examine the notification ID to determine whether it is an 
event that you wish to handle. The ID is contained in the high word of the wParam parameter. The sample uses 
bitwise operators to extract the ID. If the user has made or changed their selection, the ID will be lbn_selchange . 

When LBN_SELCHANGE is received, the sample gets the index of the selected item by sending the control a 
LB_GETCURSEL message. To get the text, you first create a StringBuilder. You then send the control an lb_gettext 
message. Pass the empty StringBuilder object as the wParam parameter. When sendMessage returns, the 
StringBuilder will contain the text of the selected item. This use of SendMessage requires yet another PInvoke 
declaration. 

Finally, set handled to true to indicate that the message has been handled. 

See also 

• HwndHost 

• WPF and Win32 Interoperation 

• Walkthrough: My first WPF desktop application 

















Walkthrough: Hosting WPF Content in Win32 

3/12/2020 • 16 minutes to read ^ Edit Online 


Windows Presentation Foundation (WPF) provides a rich environment for creating applications. However, when 
you have a substantial investment in Win32 code, it might be more effective to add WPF functionality to your 
application rather than rewriting your original code. WPF provides a straightforward mechanism for hosting WPF 
content in a Win32 window. 

This tutorial describes how to write a sample application. Hosting WPF Content in a Win32 Window Sample, that 
hosts WPF content in a Win32 window. You can extend this sample to host any Win32 window. Because it involves 
mixing managed and unmanaged code, the application is written in C + +/CLI. 

Requirements 

This tutorial assumes a basic familiarity with both WPF and Win32 programming. For a basic introduction to WPF 
programming, see Getting Started. For an introduction to Win32 programming, you should reference any of the 
numerous books on the subject, in particular Programming Windowsby Charles Petzold. 

Because the sample that accompanies this tutorial is implemented in C + +/CLI, this tutorial assumes familiarity 
with the use of C + + to program the Windows API plus an understanding of managed code programming. 
Familiarity with C + +/CLI is helpful but not essential. 


NOTE 

This tutorial includes a number of code examples from the associated sample. However, for readability, it does not include 
the complete sample code. For the complete sample code, see Hosting WPF Content in a Win32 Window Sample. 


The Basic Procedure 

This section outlines the basic procedure you use to host WPF content in a Win32 window. The remaining sections 
explain the details of each step. 

The key to hosting WPF content on a Win32 window is the HwndSource class. This class wraps the WPF content in 
a Win32 window, allowing it to be incorporated into your user interface (Ul) as a child window. The following 
approach combines the Win32 and WPF in a single application. 

1. Implement your WPF content as a managed class. 

2. Implement a Windows application with C + +/CLI. If you are starting with an existing application and 
unmanaged C+ + code, you can usually enable it to call managed code by changing your project settings to 
include the /cir compiler flag. 

3. Set the threading model to single-threaded apartment (STA). 

4. Handle the WM_CREATEnotification in your window procedure and do the following: 

a. Create a new HwndSource object with the parent window as its parent parameter. 

b. Create an instance of your WPF content class. 

c. Assign a reference to the WPF content object to the RootVisual property of the HwndSource. 

d. Get the HWND for the content. The Handle property of the HwndSource object contains the window 







handle (HWND). To get an HWND that you can use in the unmanaged part of your application, cast 
Handle.ToPointenO to an HWND. 

5. Implement a managed class that contains a static field to hold a reference to your WPF content. This class 
allows you to get a reference to the WPF content from your Win32 code. 

6. Assign the WPF content to the static field. 

7. Receive notifications from the WPF content by attaching a handler to one or more of the WPF events. 

8. Communicate with the WPF content by using the reference that you stored in the static field to set 
properties, and so on. 


NOTE 

You can also use Extensible Application Markup Language (XAML) to implement your WPF content. However, you will have 
to compile it separately as a dynamic-link library (DLL) and reference that DLL from your Win32 application. The remainder 
of the procedure is similar to that outlined above. 


Implementing the Host Application 

This section describes how to host WPF content in a basic Win32 application. The content itself is implemented in 
C-I-+/CLI as a managed class. For the most part, it is straightforward WPF programming. The key aspects of the 
content implementation are discussed in Implementing the WPF Content. 

• The Basic Application 

• Hosting the WPF Content 

• Holding a Reference to the WPF Content 

• Communicating with the WPF Content 

The Basic Application 

The starting point for the host application was to create a Visual Studio 2005 template. 

1. Open Visual Studio 2005, and select New Project from the File menu. 

2. Select Win32 from the list of Visual C-I-+ project types. If your default language is not C++, you will find 
these project types under Other Languages. 

3. Select a Win32 Project template, assign a name to the project and click OK to launch the Win32 
Application Wizard. 

4. Accept the wizard's default settings and click Finish to start the project. 

The template creates a basic Win32 application, including: 

• An entry point for the application. 

• A window, with an associated window procedure (WndProc). 

• A menu with File and Help headings. The File menu has an Exit item that closes the application. The Help 
menu has an About item that launches a simple dialog box. 

Before you start writing code to host the WPF content, you need to make two modifications to the basic template. 

The first is to compile the project as managed code. By default, the project compiles as unmanaged code. However, 
because WPF is implemented in managed code, the project must be compiled accordingly. 



1. Right-click the project name in Solution Explorer and select Properties from the context menu to launch 
the Property Pages dialog box. 

2. Select Configuration Properties from the tree view in the left pane. 

3. Select Common Language Runtime support from the Project Defaults list in the right pane. 

4. SelectCommon Language Runtime Support (/cir) from the drop-down list box. 

NOTE 

This compiler flag allows you to use managed code in your application, but your unmanaged code will still compile as before. 


WPF uses the single-threaded apartment (STA) threading model. In order to work properly with the WPF content 
code, you must set the application's threading model to STA by applying an attribute to the entry point. 

[System::STAThreadAttribute] //Needs to be an STA thread to play nicely with WPF 
int APIENTRY _tWinMain(HINSTANCE hinstance, 

HINSTANCE hPrevInstancej 
LPTSTR IpCmdLinej 

int nCmdShow) 


Hosting the WPF Content 

The WPF content is a simple address entry application. It consists of several TextBox controls to take user name, 
address, and so on. There are also two Button controls, OK and Cancel. When the user clicks OK, the button's Click 
event handler collects the data from the TextBox controls, assigns it to corresponding properties, and raises a 
custom event, onButtonciicked . When the user clicks Cancel, the handler simply raises onButtonciicked .The 
event argument object for OnButtonciicked contains a Boolean field that indicates which button was clicked. 

The code to host the WPF content is implemented in a handler for the WM_CREATE notification on the host 
window. 


case WM_CREATE : 

GetClientRect(hWnd, Srect); 

wpfHwnd = GetHwnd(hWndj rect.right-375j 0, 375j 250)j 
CreateDataDisplay(hWndj 275, rect.right-375, 375); 

CreateRadioButtons(hWnd); 

break; 

The GetHwnd method takes size and position information plus the parent window handle and returns the window 
handle of the hosted WPF content. 


NOTE 

You cannot use a #using directive for the System:: windows:: interop namespace. Doing SO creates a name collision 
between the MSG structure in that namespace and the MSG structure declared in winuser.h. You must instead use fully- 
qualified names to access the contents of that namespace. 








HWND GetHwnd(HWND parent^ int Xj int y, int width, int height) 

{ 

System: :Windows: ilntenop: :HwndSour'ceParameters'' sourceParams = gcnew 
System: :Windows: :Inter'op: :HwndSour'ceParameters( 

"hi" // NAME 

); 

sour'ceParams->PositionX = x; 

sounceParams-xPositionY = y; 

sounceParams-xHeight = height; 

sounceParams-xWidth = width; 

sounceParams-xParentWindow = IntPtr(parent); 

sounceParams-xWindowStyle = WS_VISIBLE | WS_CHILD; // style 

System::Windows::Interop::HwndSource'' source = gcnew System::Windows::Interop::HwndSource(*sourceParams); 
WPFPage ^'myPage = gcnew WPFPage(width, height); 

//Assign a reference to the WPF page and a set of UI properties to a set of static properties in a class 
//that is designed for that purpose. 

WPFPageElost: :hostedPage = myPage; 

WPFPageElost: :initBackBrush = myPage->Background; 

WPFPageElost: :initFontFamily = myPage->DefaultFontFamily; 

WPFPageElost: :initFontSize = myPage->DefaultFontSize; 

WPFPageElost: :initFontStyle = myPage->DefaultFontStyle; 

WPFPageElost: :initFontWeight = myPage->DefaultFontWeight; 

WPFPageElost: :initForeBrush = myPage->DefaultForeBrush; 

myPage->OnButtonClicked += gcnew WPFPage::ButtonClickElandler(WPFButtonClicked); 

source-xRootVisual = myPage; 

return (EIWND) source->Elandle.ToPointer(); 


You cannot host the WPF content directly in your application window. Instead, you first create an HwndSource 
object to wrap the WPF content. This object is basically a window that is designed to host a WPF content. You host 
the FlwndSource object in the parent window by creating it as a child of a Win32 window that is part of your 
application. The HwndSource constructor parameters contain much the same information that you would pass to 
CreateWindow when you create a Win32 child window. 

You next create an instance of the WPF content object. In this case, the WPF content is implemented as a separate 
class, WPFPage , using C + +/CLI. You could also implement the WPF content with XAML. However, to do so you need 
to set up a separate project and build the WPF content as a DLL. You can add a reference to that DLL to your 
project, and use that reference to create an instance of the WPF content. 

You display the WPF content in your child window by assigning a reference to the WPF content to the RootVisual 
property of the HwndSource. 

The next line of code attaches an event handler, wPFButtonciicked , to the WPF content onButtonciicked event. This 
handler is called when the user clicks the OK or Cancel button. See communicating_with_the_WPF content for 
further discussion of this event handler. 

The final line of code shown returns the window handle (HWND) that is associated with the HwndSource object. 
You can use this handle from your Win32 code to send messages to the hosted window, although the sample does 
not do so. The HwndSource object raises an event every time it receives a message. To process the messages, call 
the AddHook method to attach a message handler and then process the messages in that handler. 

Holding a Reference to the WPF Content 

For many applications, you will want to communicate with the WPF content later. For example, you might want to 
modify the WPF content properties, or perhaps have the HwndSource object host different WPF content. To do 
this, you need a reference to the HwndSource object or the WPF content. The HwndSource object and its 
associated WPF content remain in memory until you destroy the window handle. However, the variable you assign 
to the HwndSource object will go out of scope as soon as you return from the window procedure. The customary 
way to handle this issue with Win32 applications is to use a static or global variable. Unfortunately, you cannot 
assign a managed object to those types of variables. You can assign the window handle associated with 






HwndSource object to a global or static variable, but that doe not provide access to the object itself. 

The simplest solution to this issue is to implement a managed class that contains a set of static fields to hold 
references to any managed objects that you need access to. The sample uses the wpFPageHost class to hold a 
reference to the WPF content, plus the initial values of a number of its properties that might be changed later by 
the user. This is defined in the header. 


public nef class WPFPageHost 

{ 

public: 

WPFPageHostO; 

static WPFPage'' hostedPage; 

//initial property settings 

static System: :Windows::Media::Brush'' initBackBrush; 
static System:iWindows::Media::Brush^ initForeBrush; 
static System: :Windows: :Media:: FontFamily'' initFontFamily; 
static System::Windows::FontStyle initFontStyle; 
static System::Windows::FontWeight initFontWeight; 
static double initFontSize; 

}; 

The latter part of the GetHwnd function assigns values to those fields for later use while myPage is still in scope. 

Communicating with the WPF Content 

There are two types of communication with the WPF content. The application receives information from the WPF 
content when the user clicks the OK or Cancel buttons. The application also has a Ul that allows the user to 
change various WPF content properties, such as the background color or default font size. 

As mentioned above, when the user clicks either button the WPF content raises an onButtonciicked event. The 
application attaches a handler to this event to receive these notifications. If the OK button was clicked, the handler 
gets the user information from the WPF content and displays it in a set of static controls. 







void WPFButtonClicked(Object ''sender, MyPageEventArgs ''args) 

{ 

if(args->IsOK) //display data if OK button was clicked 

{ 

WPFPage ''myPage = WPFPageFlost: : hostedPage; 

LPCWSTR userName = (LPCWSTR) InteropServices: :Manshal: :StringToFIGlobalAuto("Name: " + myPage- 
>EnteredName).ToPointer(); 

SetWindowText(nameLabel, userName)j 

LPCWSTR userAddress = (LPCWSTR) InteropServices::Marshal::StringToFIGlobalAuto("Address: " + myPage- 
>EnteredAddress).ToPointer(); 

SetWindowText(addressLabel, userAddress)j 

LPCWSTR userCity = (LPCWSTR) InteropServices: :Marshal::StringToFIGlobalAuto("City: " + myPage- 
>EnteredCity).ToPointer(); 

SetWindowText(cityLabel, userCity); 

LPCWSTR userState = (LPCWSTR) InteropServices::Marshal::StringToFIGlobalAuto("State: " + myPage- 
>EnteredState).ToPointer(); 

SetWindowText(stateLabel, userState); 

LPCWSTR userZip = (LPCWSTR) InteropServices::Marshal::StringToFIGlobalAuto("Zip: " + myPage- 
>EnteredZip).ToPointer(); 

SetWindowText(zipLabel, userZip); 

} 

else 

{ 

SetWindowText(nameLabel, L"Name: "); 

SetWindowText(addressLabel, L"Address: "); 

SetWindowText(cityLabel, L"City: "); 

SetWindowText(stateLabel, L"State: "); 

SetWindowText(zipLabel, L"Zip: "); 

} 

} 

The handler receives a custom event argument object from the WPF content, MyPageEventArgs . The object's isok 
property is set to true if the OK button was clicked, and false if the Cancel button was clicked. 

If the OK button was clicked, the handler gets a reference to the WPF content from the container class. It then 
collects the user information that is held by the associated WPF content properties and uses the static controls to 
display the information on the parent window. Because the WPF content data is in the form of a managed string, it 
has to be marshaled for use by a Win32 control. If the Cancel button was clicked, the handler clears the data from 
the static controls. 

The application Ul provides a set of radio buttons that allow the user to modify the background color of the WPF 
content, and several font-related properties. The following example is an excerpt from the application's window 
procedure (WndProc) and its message handling that sets various properties on different messages, including the 
background color. The others are similar, and are not shown. See the complete sample for details and context. 







case WM_COMMAND: 

wmid = LOWORD(wParam); 
wmEvent = HIWORD(wParam); 

switch (wmId) 

{ 

//Menu selections 
case IDM_ABOUT: 

DialogBox(hInst, MAKEINTRESOURCE(IDD_ABOUTBOX), hWnd, About); 
break; 

case IDM_EXIT: 

DestroyWindow(hWnd); 
break; 

//RadioButtons 

case IDC_ORIGINALBACKGROUND : 

WPFPageHost::hostedPage->Background = WPFPageHost::initBackBrush; 
break; 

case IDC_LIGHTGREENBACKGROUND : 

WPFPageHost::hostedPage->Background = gcnew SolidColorBrush(Colors::LightGreen); 
break; 

case IDC_LIGHTSALMONBACKGROUND : 

WPFPageHost::hostedPage->Background = gcnew SolidColorBrush(Colors::LightSalmon); 
break; 

To set the background color, get a reference to the WPF content ( hostedPage ) fronn WPFPageHost and set the 
background color property to the appropriate color. The sample uses three color options: the original color, light 
green, or light salmon. The original background color is stored as a static field in the WPFPageHost class. To set the 
other two, you create a new SolidColorBrush object and pass the constructor a static colors value from the Colors 
object. 

Implementing the WPF Page 

You can host and use the WPF content without any knowledge of the actual implementation. If the WPF content 
had been packaged in a separate DLL, it could have been built in any common language runtime (CLR) language. 
Following is a brief walkthrough of the C+ +/CLI implementation that is used in the sample. This section contains 
the following subsections. 

• Layout 

• Returning the Data to the Host Window 

• Setting the WPF Properties 

Layout 

The Ul elements in the WPF content consist of five TextBox controls, with associated Label controls: Name, Address, 
City, State, and Zip. There are also two Button controls, OK and Cancel 

The WPF content is implemented in the wPFPage class. Layout is handled with a Grid layout element. The class 
inherits from Grid, which effectively makes it the WPF content root element. 

The WPF content constructor takes the required width and height, and sizes the Grid accordingly. It then defines 
the basic layout by creating a set of ColumnDefinition and RowDefinition objects and adding them to the Grid 
object base ColumnDefinitions and RowDefinitions collections, respectively. This defines a grid of five rows and 
seven columns, with the dimensions determined by the contents of the cells. 






WPFPage::WPFPage(int allottedwidth, int allotedHeight) 

{ 

ar'ray<ColumnDefinition '' columnDef = gcnew array<ColumnDefinition ''> (4); 
ar'ray<RowDefinition ''> '' nowDef = gcnew array<RowDefinition ''> (6)j 

this->Fleight = allotedhleight; 
this->Wldth = allottedWldth; 

this->Backgnound = gcnew SolidColorBrush(Colors::LightGray); 

//Set up the Grid's row and column definitions 
for(int i=0; i<4; i++) 

{ 

columnDef[i] = gcnew ColumnDefinition(); 

columnDef[i]->Width = GridLength(l, GridUnitType::Auto); 

this->ColumnDefinitions->Add(columnDef[i])j 

} 

for(int i=0; i<6; i++) 

{ 

rowDef[i] = gcnew RowDefinition(); 

rowDef[i]->Helght = GridLength(l, GridUnitType::Auto); 
this->RowDefinitions->Add(rowDef[i]); 

} 


Next, the constructor adds the Ul elements to the Grid. The first element is the title text, which is a Label control 
that is centered in the first row of the grid. 

//Add the title 

titleText = gcnew Label(); 

titleText->Content = "Simple WPF Control"; 

titleText->HorizontalAlignment = System::Windows::HorizontalAlignment::Center; 
titleText->Margin = Thickness(10j S, 1%, 0); 
titleText->FontWeight = FontWeights::Bold; 
titleText->FontSize = 14; 

Grid::SetColumn(titleTextj 0); 

Grid::SetRow(titleText, 0); 

Grid::SetColumnSpan(titleTextj 4); 
this->Children->Add(titleText); 


The next row contains the Name Label control and its associated TextBox control. Because the same code is used 
for each label/textbox pair, it is placed in a pair of private methods and used for all five label/textbox pairs. The 
methods create the appropriate control, and call the Grid class static SetColumn and SetRow methods to place the 
controls in the appropriate cell. After the control is created, the sample calls the Add method on the Children 
property of the Grid to add the control to the grid. The code to add the remaining label/textbox pairs is similar. See 
the sample code for details. 

//Add the Name Label and TextBox 
nameLabel = CreateLabel(0j 1, "Name"); 
this->Childnen->Add(nameLabel); 
nameTextBox = CneateTextBox(lj 1, 3); 
this->Childnen->Add(nameTextBox); 


The implementation of the two methods is as follows: 





Label ''WPFPage: :CreateLabel(int column, int row. String '' text) 

{ 

Label '' newLabel = gcnew Label(); 
newLabel->Content = text; 
newLabel-xMargin = Thickness(10, 5, 10, 0); 
newLabel-xFontWeight = FontWeights::Normal; 
newLabel-xFontSlze = 12; 

Grid::SetColumn(newLabel, column); 

Grid::SetRow(newLabel, row); 
return newLabel; 

} 

TextBox ''WPFPage: :CreateTextBox(int column, int row, int span) 

{ 

TextBox ''newTextBox = gcnew TextBox(); 
newTextBox-xMargin = Thickness(10, 5, 10, 0); 

Grid::SetColumn(newTextBox, column); 

Grid::SetRow(newTextBox, row); 

Grid::SetColumnSpan(newTextBox, span); 
return newTextBox; 

} 


Finally, the sample adds the OK and Cancel buttons and attaches an event handler to their Click events. 

//Add the Buttons and atttach event handlers 
okButton = CreateButton(0, 5, "OK"); 
cancelButton = CreateButton(l, 5, "Cancel"); 
this->Children->Add(okButton); 
this->Children->Add(cancelButton); 

okButton-xClick += gcnew RoutedEventHandler(this, &WPFPage::ButtonClicked); 
cancelButton-xClick += gcnew RoutedEventHandler(this, &WPFPage::ButtonClicked); 


Returning the Data to the Host Window 

When either button is clicked, its Click event is raised. The host window could simply attach handlers to these 
events and get the data directly from the TextBox controls. The sample uses a somewhat less direct approach. It 
handles the Click within the WPF content, and then raises a custom event onButtonciicked , to notify the WPF 
content. This allows the WPF content to do some parameter validation before notifying the host. The handler gets 
the text from the TextBox controls and assigns it to public properties, from which the host can retrieve the 
information. 

The event declaration, in WPFPage.h: 

public: 

delegate void ButtonClickHandler(Object MyPageEventArgs ''); 

WPFPageO; 

WPFPage(int height, int width); 

event ButtonClickHandler ''OnButtonClicked; 


The Click event handler, in WPFPage.cpp: 





void WPFPage: :ButtonClicked(Object "senderj RoutedEventArgs ''args) 

{ 

//TODO: validate input data 
bool okClicked = true; 
if(sender == cancelButton) 
okClicked = false; 

EnteredName = nameTextBox->Text; 

EnteredAddress = addressTextBox->Text; 

EnteredCity = cityTextBox->Text; 

EnteredState = stateTextBox->Text; 

EnteredZip = zipTextBox->Text; 

OnButtonClicked(this, gcnew MyPageEventArgs(okClicked)); 


Setting the WPF Properties 

The Win32 host allows the user to change several WPF content properties. From the Win32 side, it is simply a 
matter of changing the properties. The implementation in the WPF content class is somewhat more complicated, 
because there is no single global property that controls the fonts for all controls. Instead, the appropriate property 
for each control is changed in the properties' set accessors. The following example shows the code for the 
DefauitFontFamiiy property. Setting the property calls a private method that in turn sets the FontFamily 
properties for the various controls. 

From WPFPage.h: 

property FontFamily'' DefauitFontFamiiy 

{ 

FontFamily'' get() {return _defaultFontFamily;} 
void set(FontFamily'' value) {SetFontFamily(value);} 


From WPFPage.cpp: 

void WPFPage: :SetFontFamily(FontFamily'' newFontFamily) 

{ 

_defaultFontFamily = newFontFamily; 
titleText->FontFamily = newFontFamily; 
nameLabel->FontFamily = newFontFamily; 
addressLabel-xFontFamily = newFontFamily; 
cityLabel->FontFamily = newFontFamily; 
stateLabel-xFontFamily = newFontFamily; 
zipLabel-xFontFamily = newFontFamily; 


See also 


• FlwndSource 

• WPF and Win32 Interoperation 






Walkthrough: Host a WPF Clock in Win32 

2/11/2020 • 8 minutes to read ^ Edit Online 


To put WPF inside Win32 applications, use HwndSource, which provides the HWND that contains your WPF 
content. First you create the HwndSource, giving it parameters similar to CreateWindow. Then you tell the 
HwndSource about the WPF content you want inside it Finally, you get the HWND out of the HwndSource. This 
walkthrough illustrates how to create a mixed WPF inside Win32 application that reimplements the operating 
system Date and Time Properties dialog. 

Prerequisites 

See WPF and Win32 Interoperation. 

How to Use This Tutorial 

This tutorial concentrates on the important steps of producing an interoperation application. The tutorial is backed 
by a sample, Win32 Clock Interoperation Sample, but that sample is reflective of the end product. This tutorial 
documents the steps as if you were starting with an existing Win32 project of your own, perhaps a pre-existing 
project, and you were adding a hosted WPF to your application. You can compare your end product with Win32 
Clock Interoperation Sample. 

A Walkthrough of Windows Presentation Framework Inside Win32 
(HwndSource) 

The following graphic shows the intended end product of this tutorial: 



You can recreate this dialog by creating a C + + Win32 project in Visual Studio, and using the dialog editor to create 
the following: 































Date and Time Properties 


Date & Time Time Zone 
Date 


March 


2005 


Sun Mon Tue Wed Thu 

Fri 

Sat 

27 

28 
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15 
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19 

20 

21 

22 

23 

24 

25 

26 
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28 

29 

30 

31 


2 


4 

5 

6 

7 

8 
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Time 

Insert clock here 


Current time zone: Pacific Standard Time 


Ok 


Cancel 


(You do not need to use Visual Studio to use HwndSource, and you do not need to use C + + to write Win32 
programs, but this is a fairly typical way to do it, and lends itself well to a stepwise tutorial explanation). 

You need to accomplish five particular substeps in order to put a WPF clock into the dialog: 

1 . Enable your Win32 project to call managed code (/cir) by changing project settings in Visual Studio. 

2. Create a WPFPage in a separate DLL. 

3. Put that WPFPage inside an HwndSource. 

4. Get an HWND for that Page using the Handle property. 

5. Use Win32 to decide where to place the HWND within the larger Win32 application 

/cIr 

The first step is to turn this unmanaged Win32 project into one that can call managed code. You use the /cir 
compiler option, which will link to the necessary DLLs you want to use, and adjust the Main method for use with 
WPF. 

To enable the use of managed code inside the C + + project: Right-click on win32clock project and select 
Properties. On the General property page (the default), change Common Language Runtime support to /cir . 

Next, add references to DLLs necessary for WPF: PresentationCore.dll, PresentationFramework.dll, System.dll, 
WindowsBase.dll, UIAutomationProvider.dll, and UIAutomationTypes.dll. (Following instructions assume the 
operating system is installed on C: drive.) 

1 . Right-click win32clock project and select References..., and inside that dialog: 

2. Right-click win32clock project and select References.... 

3. Click Add New Reference, click Browse tab, enter C:\Program Files\Reference 
Assemblies\Microsoft\Framework\v3.0\PresentationCore.dll, and click OK. 

4. Repeat for PresentationFramework.dll: C:\Program Files\Reference 
Assemblies\Microsoft\Framework\v3.0\PresentationFramework.dll. 

5. Repeat for WindowsBase.dll: C:\Program Files\Reference 
Assemblies\Microsoft\Framework\v3.0\WindowsBase.dll. 

6. Repeat for UIAutomationTypes.dll: C:\Program Files\Reference 



























Assemblies\Microsoft\Framework\v3.0\UIAutomationTypes.dll. 

7. Repeat for UIAutomationProvider.dll: C:\Program Files\Reference 
Assemblies\Microsoft\Framework\v3.0\UIAutomationProvider.dll. 

8. Click Add New Reference, select System.dll, and click OK. 


9. Click OK to exit the win32clock Property Pages for adding references. 



This attribute tells the common language runtime (CLR) that when it initializes Component Object Model (COM), it 
should use a single threaded apartment model (STA), which is necessary for WPF (and Windows Forms). 


Create a Windows Presentation Framework Page 

Next, you create a DLL that defines a WPFPage. It's often easiest to create the WPFPage as a standalone application, 
and write and debug the WPF portion that way. Once done, that project can be turned into a DLL by right-clicking 
the project, clicking on Properties, going to the Application, and changing Output type to Windows Class Library. 

The WPF dll project can then be combined with the Win32 project (one solution that contains two projects) - right- 
click on the solution, select Add\Existing Project. 

To use that WPF dll from the Win32 project, you need to add a reference: 

1. Right-click win32clock project and select References.... 

2. Click Add New Reference. 

3. Click the Projects tab. Select WPFCIock, click OK. 

4. Click OK to exit the win32clock Property Pages for adding references. 

HwndSource 

Next, you use HwndSource to make the WPFPage look like an HWND. You add this block of code to a C + + file: 






namespace ManagedCode 

{ 

using namespace System; 

using namespace System::Windows; 

using namespace System::Windows::Interop; 

using namespace System::Windows::Hedia; 

HWND GetHwnd(HWND parent^ int Xj int y, int width, int height) { 
HwndSounce'' source = gcnew HwndSource( 

0, // class style 

WS_VISIBLE I WS_CHILD, // style 

0, // exstyle 

X, y, width, height, 

"hi", // NAME 

IntPtr(parent) // parent window 

); 

UIElement'' page = gcnew WPFClock: :Clock(); 

source-xRootVisual = page; 

return (HWND) source->Handle.ToPointer(); 

} 

} 

} 


This is a long piece of code that could use some explanation. The first part is various clauses so that you do not 
need to fully qualify all the calls: 

namespace ManagedCode 

{ 

using namespace System; 

using namespace System::Windows; 

using namespace System::Windows::Interop; 

using namespace System::Windows::Hedia; 


Then you define a function that creates the WPF content, puts an HwndSource around it, and returns the HWND: 

HWND GetHwnd(HWND parent, int x, int y, int width, int height) { 

First you create an HwndSource, whose parameters are similar to CreateWindow: 

HwndSource* source = gcnew HwndSource( 

0, // class style 

WS_VISIBLE I WS_CHILD, // style 

0, // exstyle 

X, y, width, height, 

"hi", // NAME 

IntPtr(parent) // parent window 

); 


Then you create the WPF content class by calling its constructor: 

UIElement* page = gcnew WPFClock::Clock(); 


You then connect the page to the HwndSource: 

source->RootVisual = page; 





And in the final line, return the HWND for the HwndSource: 


return (HWND) source->Handle.ToPointer(); 


Positioning the Hwnd 

Now that you have an HWND that contains the WPF clock, you need to put that HWND inside the Win32 dialog. If 
you knew just where to put the HWND, you would Just pass that size and location to the GetHwnd function you 
defined earlier. But you used a resource file to define the dialog, so you are not exactly sure where any of the 
HWNDs are positioned. You can use the Visual Studio dialog editor to put a Win32 STATIC control where you want 
the clock to go ("Insert clock here"), and use that to position the WPF clock. 

Where you handle WM_INITDIALOG, you use GetDigitem to retrieve the HWND for the placeholder STATIC: 

HWND placeholder = GetDlgItem(hDlg, IDC_CLOCK)j 


You then calculate the size and position of that placeholder STATIC, so you can put the WPF clock in that place: 
RECT rectangle; 

GetWindowRect(placeholderj Srectangle); 

int width = rectangle.right - rectangle.leftj 

int height = rectangle.bottom - rectangle.top; 

POINT point; 

point.X = rectangle.left; 
point.y = rectangle.top; 

result = HapWindowPoints(NULLj hDlg, &point, 1); 


Then you hide the placeholder STATIC: 

ShowWindow(placeholder, SW_HIDE); 


And create the WPF clock HWND in that location: 


HWND clock = ManagedCode::GetHwnd(hDlg, point.x, point.y, width, height); 


To make the tutorial interesting, and to produce a real WPF clock, you will need to create a WPF clock control at this 
point. You can do so mostly in markup, with just a few event handlers in code-behind. Since this tutorial is about 
interoperation and not about control design, complete code for the WPF clock is provided here as a code block, 
without discrete instructions for building it up or what each part means. Feel free to experiment with this code to 
change the look and feel or functionality of the control. 

Here is the markup: 

<Page x:Class="WPFClock.Clock" 

xmlns="http://schemas.micnosoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.micnosoft.com/winfx/2006/xaml" 

> 

<Grid> 

<Grid.Backgnound> 

<LinearGradientBrush StartPoint="0,0" EndPoint="0,1"> 

<GradientStop Color="#fcfcfe" Offset="0" /> 

<GradientStop Color="#f6f4f0" Offset="1.0" /> 

</tineanGnadientBnush> 

</Grid.Background> 







<Grid Name="PodClock" HorizontalAlignment="Center'" VerticalAlignment="Center"> 

<Grid. Resour'ces> 

<Storyboar'd x:Key="sb"> 

<DoubleAnlmation From="0" To="360" Duration="12:00:00" RepeatBehavior="Forever" 
Stony board. TargetName="FlourFland" 

Stonyboard.TargetProperty="(Rectangle.RendenTnansfonm).(RotateTransform.Angle)' 
/> 

<DoubleAnimation From="0" To="360" Duration="01:00:00" RepeatBehavion="Forever" 
Storyboard.TargetName="MinuteHand" 

Storyboard.TargetPropenty="(Rectangle.RendenTnansfonm).(RotateTransform.Angle)' 
/> 

<DoubleAnlmation From="0" To="360" Duration="0:l:00" RepeatBehavior="Forever" 
Storyboard.TargetName="Secondhand" 

Storyboard.TargetProperty="(Rectangle.RenderTransform).(RotateTransform.Angle)' 
/> 

</Storyboard> 

</Grid.Resources> 

<Ellipse Width="108" Height="108" StrokeThickness="3"> 

<Ellipse.Stroke> 

<LinearGradientBrush> 

<GradientStop Color="LightBlue" Offset="0" /> 

<GradientStop Color="DarkBlue" Offset="l" /> 

</tinearGradientBrush> 

</Ellipse.Stroke> 

</Ellipse> 

<Ellipse VerticalAlignment="Center" HorizontalAlignment="Center" Width="104" Height="104" 
Fill="LightBlue" StrokeThickness="3"> 

<Ellipse.Stroke> 

<LinearGradientBrush) 

<GradientStop Color="DarkBlue" Offset="0" /> 

<GradientStop Color="LightBlue" Offset="l" /> 

</tinearGradientBrush) 

</Ellipse.Stroke) 

</Ellipse) 

<Border BorderThickness="l" BorderBrush="Black" Background="White" Margin="20" 
HorizontalAlignment="Right" \/erticalAlignment="Center") 

<TextBlock IMame="MonthDay" Text="{Binding}"/) 

</Border) 

<Canvas Width="102" Height="102") 

<Ellipse Width="8" Height="8" Fill="Black" Canvas.Top="46" Canvas.teft="46" /) 
cRectangle Canvas.Top="5" Canvas.teft="48" Fill="Black" Width="4" Height="8") 
<Rectangle.RenderTransform) 

<RotateTransform CenterX="2" CenterY="46" Angle="0" /) 

</Rectangle.RenderTransform) 

</Rectangle) 

<Rectangle Canvas.Top="5" Canvas.teft="49" Fill="Black" Width="2" Height="6") 
<Rectangle.RenderTransform) 

<RotateTransform CenterX="2" CenterY="46" Angle="30" /) 

</Rectangle.RenderTransform) 

</Rectangle) 

<Rectangle Canvas.Top="5" Canvas.teft="49" Fill="Black" Width="2" Height="6") 
<Rectangle.RenderTransform) 

cRotateTransform CenterX="2" CenterY="46" Angle="60" /) 

</Rectangle.RenderTransform) 

</Rectangle) 

<Rectangle Canvas.Top="5" Canvas.teft="48" Fill="Black" Width="4" Height="8") 
<Rectangle.RenderTransform) 

cRotateTransform CenterX="2" CenterY="46" Angle="90" /) 

</Rectangle.RenderTransform) 

</Rectangle) 

<Rectangle Canvas.Top="5" Canvas.teft="49" Fill="Black" Width="2" Height="6") 
cRectangle.RenderTransform) 

<RotateTransform CenterX="2" CenterY="46" Angle="120" /) 

</Rectangle.RenderTransform) 

</Rectangle) 

cRectangle Canvas.Top="5" Canvas.teft="49" Fill="Black" Width="2" Height="6") 
<Rectangle.RenderTransform) 


<RotateTransfortii CenterX="2" CenterY="46" Angle="150" /> 

</Rectangle. Render'Transform> 

</Rectangle> 

<Rectangle Canvas.Top="5" Canvas.Left="48" Fill="Black" Width="4" Height="8"> 
<Rectangle.RenderTransform> 

<RotateTransform CenterX="2" CenterY="46" Angle="180" /> 

</Rectangle.RendenTnansform> 

</Rectangle> 

<Rectangle Canvas .Top="5" Canvas. Left="49" Fill="Black" Width="2" Fleight="6"> 
<Rectangle.RenderTransform> 

<RotateTransform CenterX="2" CenterY="46" Angle="210" /> 

</Rectangle.RendenTnansform> 

</Rectangle> 

<Rectangle Canvas .Top="5" Canvas. Left="49" Fill="Black" Width="2" Fleight="6"> 
<Rectangle.RenderTransform> 

<RotateTransform CenterX="2" CenterY="46" Angle="240" /> 

</Rectangle.RenderTnansform> 

</Rectangle> 

<Rectangle Canvas .Top="5" Canvas. Left="48" Fill="Black" Width="4" Fleight="8"> 
<Rectangle.RenderTransform> 

<RotateTransform CenterX="2" CenterY="46" Angle="270" /> 

</Rectangle.RendenTransform> 

</Rectangle> 

<Rectangle Canvas .Top="5" Canvas. Left="49" Fill="Black" Width="2" Fleight="6"> 
<Rectangle.RenderTransform> 

cRotateTransform CenterX="2" CenterY="46" Angle="300" /> 

</Rectangle.RenderTnansform> 

</Rectangle> 

<Rectangle Canvas .Top="5" Canvas. Left="49" Fill="Black" Width="2" Fleight="6"> 
<Rectangle.RenderTransform> 

<RotateTransform CenterX="2" CenterY="46" Angle="330" /> 

</Rectangle.RendenTnansform> 

</Rectangle> 


<Rectangle x:Name="FlourFland" Canvas.Top="21" Canvas. Left="48" 
Fill="Black" Width="4" Fleight="30"> 

<Rectangle.RenderTransform> 

<RotateTransform x:Name="FlounFland2" CenterX="2" CenterY="30" /> 
</Rectangle.RendenTnansform> 

</Rectangle> 

<Rectangle x:Name="MinuteFland" Canvas.Top="6" Canvas. Left="49" 
Fill="Black" Width="2" Fleight="45"> 

<Rectangle.RenderTransform> 

<RotateTransform CenterX="l" CenterY="45" /> 

</Rectangle.RenderTnansform> 

</Rectangle> 

<Rectangle x:Name="SecondFland" Canvas.Top="4" Canvas. Left="49" 
Fill="Red" Width="l" Fleight="47"> 

<Rectangle.RenderTransform> 

cRotateTransform CenterX="0.5" CenterY="47" /> 

</Rectangle.RendenTnansform> 

</Rectangle> 

</Canvas> 

</Gnid> 

</Gnid> 

</Page> 


And here is the accompanying code-behind: 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Data; 

using System.Windows.Documents; 

using System.Windows.Media; 

using System.Windows.Media.Animation; 

using System.Windows.Shapes; 

using System.Windows.Threading; 

namespace WPFClock 

{ 

III <summary> 

III Interaction logic for Clock.xaml 
III </summary> 

public partial class Clock : Page 

{ 

private DispatcherTimer _dayTimer; 

public ClockO 

{ 

InitializeComponentO; 

this.Loaded += new RoutedEventHandler(Clock_Loaded); 

} 

void Clock_Loaded(object sender^ RoutedEventArgs e) { 

// set the datacontext to be today's date 
DateTime now = DateTime.Now; 

DataContext = now.Day .ToStringO; 

// then set up a timer to fire at the start of tomorrow, so that we can update 

// the datacontext 

_dayTimer = new DispatcherTimer(); 

_dayTimer.Interval = new TimeSpan(l, 0, 0, 0) - now.TimeOfDay; 

_dayTimer.Tick += new EventElandler(OnDayChange); 

_dayTimer.Start(); 

// finally, seek the timeline, which assumes a beginning at midnight, to the appropriate 
// offset 

Storyboard sb = (Storyboard)PodClock.FindResource("sb"); 
sb.Begin(PodClock, FlandoffBehavior.SnapshotAndReplace, true); 
sb.Seek(PodClock, now.TimeOfDay, TimeSeekOrigin.BeginTime); 

} 

private void OnDayChange(object sender, EventArgs e) 

{ 

// date has changed, update the datacontext to reflect today's date 
DateTime now = DateTime.Now; 

Datacontext = now.Day .ToStringO; 

_dayTimer.Interval = new TimeSpan(l, 0, 0, 0); 

} 

} 

} 


The final result looks like: 



Date and Time Properties 



To compare your end result to the code that produced this screenshot, see Win32 Clock Interoperation Sample. 

See also 

• HwndSource 

• WPF and Win32 Interoperation 

• Win32 Clock Interoperation Sample 


























WPF and Direct3D9 Interoperation 

1/24/2020 • 10 minutes to read • Edit Online 


You can include DirectsD9 content in a Windows Presentation Foundation (WPF) application. This topic describes 
how to create DirectsD9 content so that it efficiently interoperates with WPF. 


NOTE 

When using DirectsD9 content in WPF, you also need to think about performance. For more information about how to 
optimize for performance, see Performance Considerations for Direct3D9 and WPF Interoperability. 


Display Buffers 

The DSDImage class nnanages two display buffers, which are called the back buffer 3,^6 the front buffer. The back 
buffer is your DirectsD9 surface. Changes to the back buffer are copied forward to the front buffer when you call 
the Unlock method. 

The following illustration shows the relationship between the back buffer and the front buffer. 


UI Thread Render Thread 



Direct3D9 Device Creation 

To render Directs D9 content, you must create a Directs D9 device. There are two Directs D9 objects that you can 
use to create a device, iDinectBog and iDinectaDSEx . Use these objects to create iDinect3DDevice9 and 
iDirect3DDevice9Ex devices, respectively. 

Create a device by calling one of the following methods. 

• IDirect3D9 * Direct3DCr'eate9(UINT SDKVersion)j 

• HRESULT DinectSDCreateSExCUINT SDKVension, IDirect3D9Ex **ppD3D); 

On Windows Vista or later operating system, use the Direct3DCreate9Ex method with a display that is configured 
to use the Windows Display Driver Model (WDDM). Use the Direct3DCreate9 method on any other platform. 

Availability of the Direct3DCreate9Ex method 

The dSd9.dll has the Direct3DCreate9Ex method only on Windows Vista or later operating system. If you directly 
link the function on Windows XP, your application fails to load. To determine whether the Direct3DCreate9Ex 
method is supported, load the DLL and look for the proc address. The following code shows how to test for the 
DinectSDCreateSEx method. For a full code example, see Walkthrough: Creating DirectsD9 Content for Hosting in 
WPF. 



















HRESULT 

CRenderenManager::EnsureD3D0bjects() 

{ 

HRESULT hr = S_OK; 

HMODULE hD3D = NULL; 
if (!m_pD3D) 

{ 

hD3D = LoadLibrary(TEXT("d3d9.dll")); 

DIRECT3DCREATE9EXFUNCTION pfnCreate9Ex = (DIRECT3DCREATE9EXFUNCTION)GetProcAddress(hD3D, 
"Direct3DCreate9Ex"); 

if (pfnCreate9Ex) 

{ 

IFC((*pfnCreate9Ex)(D3D_SDK_VERSION, &m_pD3DEx)); 

IFC(m_pD3DEx->QueryInterface(_uuidof(IDirect3D9)j reinterpret_cast<void **>(&m_pD3D))); 

} 

else 

{ 

m_pD3D = Direct3DCreate9(D3D_SDK_VERSION); 
if (!m_pD3D) 

{ 

IFC(E_FAIL); 

} 

} 

m_cAdapters = m_pD3D->GetAdapterCount(); 

} 

Cleanup: 

if (hD3D) 

{ 

FreeLibrary(hD3D); 

} 

return hr; 

} 


HWND Creation 

Creating a device requires an HWND. In general, you create a dummy HWND for Direct3D9 to use. The following 
code example shows how to create a dummy HWND. 



HRESULT 

CRenderenManager::EnsureHWND() 

{ 

HRESULT hr = S_OK; 

if (!m_hwnd) 

{ 

WNDCLASS wndclass; 

wndclass.style = CS_HREDRAW | CS_VREDRAW; 
wndclass.IpfnWndProc = DefWindowProc; 
wndclass.cbClsExtra = 0; 
wndclass.cbWndExtra = 0; 
wndclass.hinstance = NULL; 

wndclass.hicon = LoadIcon(NULL, IDI_APPLICATION); 

wndclass.hCursor = LoadCursor(NULLj IDC_ARROW); 

wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH); 

wndclass.IpszMenuName = NULL; 

wndclass.IpszClassName = szAppName; 

if (!RegisterClass(&wndclass)) 

{ 

IFC(E_FAIL); 

} 

m_hwnd = CreateWindow(szAppName, 


TEXT("D3DImageSample' 



WS_OVERLAPPEDWINDOW, 



0, 

// 

Initial X 

0. 

// 

Initial Y 

0. 

// 

Width 

0. 

// 

Height 


NULL, 

NULL, 

NULL, 

NULL); 

} 

Cleanup: 

return hr; 

} 


Present Parameters 

Creating a device also requires a D3DPresent_parameters struct, but only a few parameters are important. These 
parameters are chosen to minimize the memory footprint. 

Set the BackBufferHeight and BackBufferWidth fields to 1. Setting them to 0 causes them to be set to the 
dimensions of the HWND. 

Always set the d3DCreate_multithreaded and d3DCreate_fpu_preserve flags to prevent corrupting memory used by 
Direct3D9 and to prevent DirectsD9 from changing FPU settings. 

The following code shows how to initialize the D3DPRESEnt_parameters struct. 









HRESULT 

CRenderen::Init(IDirect3D9 *pD3D, IDirect3D9Ex *pD3DEx, HWND hwndj UINT uAdapter) 

{ 

HRESULT hr = S_OK; 

D3DPRESENT_PARAMETERS d3dpp; 

ZeroMemory(&d3dpp^ sizeof(d3dpp)); 
d3dpp.Windowed = TRUE; 
d3dpp.BackBufferFormat = D3DFMT_UNKNOWN; 
d3dpp.BackBufferHeight = 1; 
d3dpp.BackBufferWidth = 1; 
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD; 

D3DCAPS9 caps; 

DWORD dwVertexProcessing; 

IFC(pD3D->GetDeviceCaps(uAdapter, D3DDEVTYPE_HAL, &caps)); 

if ((caps.DevCaps & D3DDEVCAPS_HWTRAIMSFORMANDLIGHT) == D3DDEVCAPS_HWTRANSFORMANDLIGHT) 

{ 

dwVertexProcessing = D3DCREATE_HARDWARE_VERTEXPROCESSING; 

} 

else 

{ 

dwVertexProcessing = D3DCREATE_S0FTWARE_VERTEXPR0CESSING; 

} 

if (pD3DEx) 

{ 

IDirect3DDevice9Ex *pd3dDevice = NULL; 

IFC(pD3DEx->CreateDeviceEx( 

uAdapterj 

D3DDEVTYPE_HAL, 

hwndj 

dwVertexProcessing | D3DCREATE_MULTITHREADED | D3DCREATE_FPU_PRESERVE, 

&d3dppj 

NULL, 

&m_pd3dDeviceEx 

)); 

IFC(m_pd3dDeviceEx->QueryInterface(_uuidof(IDirect3DDevice9), reinterpret_cast<void**> 

(&m_pd3dDevice))); 

} 

else 

{ 

assert(pD3D); 

IFC(pD3D->CreateDevice( 

uAdapter, 

D3DDEVTYPE_HAL, 

hwnd, 

dwVertexProcessing | D3DCREATE_MULTITHREADED | D3DCREATE_FPU_PRESERVE, 

&d3dpp, 

&m_pd3dDevice 

)); 

} 

Cleanup: 

return hr; 

} 


Creating the Back Buffer Render Target 

To display Direct3D9 content in a DBDInnage, you create a DirectsD9 surface and assign it by calling the 
SetBackBuffer nnethod. 


Verifying Adapter Support 



Before creating a surface, verify that all adapters support the surface properties you require. Even if you render to 
only one adapter, the WPF window may be displayed on any adapter in the system. You should always write 
DirectsD9 code that handles multi-adapter configurations, and you should check all adapters for support, because 
WPF might move the surface among the available adapters. 

The following code example shows how to check all adapters on the system for Direct3D9 support. 



HRESULT 

CRenderenManager: :TestSur'faceSettings() 

{ 

HRESULT hr = S_OK; 

D3DF0RHAT fmt = m_fUseAlpha ? D3DFMT_A8R8G8B8 : D3DFMT_X8R8G8B8; 

// 

// We test all adapters because because we potentially use all adapters. 

// But even if this sample only rendered to the default adapter^ you 
// should check all adapters because WPF may move your surface to 
// another adapter for you! 

// 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

// Can we get HW rendering? 

IFC(m_pD3D->CheckDeviceType( 

i. 

D3DDEVTYPE_HAL, 

D3DFMT_X8R8G8B8, 
fmt j 
TRUE 
)); 

// Is the format okay? 

IFC(m_pD3D->CheckDeviceFormat( 

D3DDEVTYPE_HAL, 

D3DFMT_X8R8G8B8, 

D3DUSAGE_RENDERTARGET | D3DUSAGE_DYNAMIC, // We'll use dynamic when on XP 
D3DRTYPE_SURFACE, 
fmt 
)); 

// D3DImage only allows multisampling on 9Ex devices. If we can't 
// multisamplej overwrite the desired number of samples with 0. 
if (m_pD3DEx && m_uNumSamples > 1) 

{ 

assert(m_uNumSamples <= 16); 

if (FAILED(m_pD3D->CheckDeviceMultiSampleType( 
i. 

D3DDEVTYPE_HAL, 

fmt, 

TRUE, 

static_cast<D3DMULTISAHPLE_TYPE>(m_uNumSamples), 

NULL 

))) 

{ 

m_uNumSamples = 0; 

} 

} 

else 

{ 

m_uNumSamples = 0; 

} 

} 

Cleanup: 

return hr; 

} 


Creating the Surface 

Before creating a surface, verify that the device capabilities support good performance on the target operating 



system. For more information, see Performance Considerations for DirectsD9 and WPF Interoperability. 

When you have verified device capabilities, you can create the surface. The following code example shows how to 
create the render target. 

HRESULT 

CRendenen: :Cr'eateSurface(LIINT uWidth, UINT uHeight, bool fUseAlpha, DINT m_uNumSamples) 

{ 

HRESULT hr = S_OK; 

SAFE_RELEASE(m_pd3dRTS); 

IFC(m_pd3dDevice->CreateRenderTarget( 

uWidthj 

uHeight, 

fUseAlpha ? D3DFMT_A8R8G8B8 : D3DFMT_X8R8G8B8, 
static_cast<D3DMULTISAMPLE_TYPE>(m_uNumSamples) j 
0 . 

m_pd3dDeviceEx ? FALSE : TRUE^ // Lockable RT required for good XP perf 
&m_pd3dRTS, 

HULL 

)); 

IFC(m_pd3dDevice->SetRenderTarget(0, m_pd3dRTS)); 

Cleanup: 

return hr; 

} 

WDDM 

On Windows Vista and later operating systems, which are configured to use the WDDM, you can create a render 
target texture and pass the level 0 surface to the SetBackBuffer method. This approach is not recommended on 
Windows XP, because you cannot create a lockable render target texture and performance will be reduced. 

Handling Device State 

The DSDImage class manages two display buffers, which are called the back buffer and the front buffer. The back 
buffer is your DirectSD surface. Changes to the back buffer are copied forward to the front buffer when you call 
the Unlock method, where it is displayed on the hardware. Occasionally, the front buffer becomes unavailable. This 
lack of availability can be caused by screen locking, full-screen exclusive DirectSD applications, user-switching, or 
other system activities. When this occurs, your WPF application is notified by handling the 
IsFrontBufferAvailableChanged event. How your application responds to the front buffer becoming unavailable 
depends on whether WPF is enabled to fall back to software rendering. The SetBackBuffer method has an overload 
that takes a parameter that specifies whether WPF falls back to software rendering. 

When you call the SetBackBuffer{D3DResourceType, IntPtr) overload or call the SetBackBuffer(D3DResourceType, 
IntPtr, Boolean) overload with the enabieSoftwareFaiiback parameter set to false , the rendering system releases 
its reference to the back buffer when the front buffer becomes unavailable and nothing is displayed. When the 
front buffer is available again, the rendering system raises the IsFrontBufferAvailableChanged event to notify your 
WPF application. You can create an event handler for the IsFrontBufferAvailableChanged event to restart rendering 
again with a valid Direct3D surface. To restart rendering, you must call SetBackBuffer. 

When you call the SetBackBuffer{D3DResourceType, IntPtr, Boolean) overload with the enabieSoftwareFaiiback 
parameter set to true , the rendering system retains its reference to the back buffer when the front buffer 
becomes unavailable, so there is no need to call SetBackBuffer when the front buffer is available again. 

When software rendering is enabled, there may be situations where the user's device becomes unavailable, but the 
rendering system retains a reference to the DirectSD surface. To check whether a DirectsD9 device is unavailable. 







call the TestcoopenativeLevei method. To check a Direct3D9Ex devices Call the Checkoevicestate method, because 
the TestcoopenativeLevei method is deprecated and always returns success. If the user device has become 
unavailable, call SetBackBuffer to release WPF's reference to the back buffer. If you need to reset your device, call 
SetBackBuffer with the backsuffen parameter set to null , and then call SetBackBuffer again with backsuffen set 
to a valid DirectSD surface. 

Call the Reset method to recover from an invalid device only if you implement multi-adapter support. Otherwise, 
release all DirectsD9 interfaces and re-create them completely. If the adapter layout has changed, Direct3D9 
objects created before the change are not updated. 

Handling Resizing 

If a DSDImage is displayed at a resolution other than its native size, it is scaled according to the current 
BitmapScalingMode, except that Bilinear is substituted for Fant. 

If you require higher fidelity, you must create a new surface when the container of the DSDImage changes size. 
There are three possible approaches to handle resizing. 

• Participate in the layout system and create a new surface when the size changes. Do not create too many 
surfaces, because you may exhaust or fragment video memory. 

• Wait until a resize event has not occurred for a fixed period of time to create the new surface. 

• Create a DispatcherTimer that checks the container dimensions several times per second. 

Multi-monitor Optimization 

Significantly reduced performance can result when the rendering system moves a D3Dlmage to another monitor. 

On WDDM, as long as the monitors are on the same video card and you use DirectSDCneateSEx , there is no 
reduction in performance. If the monitors are on separate video cards, performance is reduced. On Windows XR 
performance is always reduced. 

When the D3Dlmage moves to another monitor, you can create a new surface on the corresponding adapter to 
restore good performance. 

To avoid the performance penalty, write code specifically for the multi-monitor case. The following list shows one 
way to write multi-monitor code. 



4. If the adapter is not the same as the adapter with the back buffer, create a new back buffer on the new 
monitor and assign it to the D3Dlmage back buffer. 


NOTE 

If the DSDImage straddles monitors, performance will be slow, except in the case of WDDM and iDirect3D9Ex on the 
same adapter. There is no way to improve performance in this situation. 


The following code example shows how to find the current monitor. 












void 

CRenderenManager::SetAdapter(POINT screenSpacePoint) 

{ 

CleanupInvalidDevicesO; 

// 

// After CleanupInvalidDeviceSj we may not have any D3D objects. Rather than 
// recreate them here^ ignore the adapter update and wait for render to recreate. 

// 

if (m_pD3D && m_rgRenderers) 

{ 

HMONITOR hMon = MonitorFromPoint(screenSpacePointj MONITOR_DEFALILTTONULL); 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

if (hMon == m_pD3D->GetAdapterMonitor(i)) 

{ 

m_pCurrentRenderer = m_rgRenderers[i]; 
break; 

} 

} 

} 

} 

Update the monitor when the DBDImage container's size or position changes, or update the monitor by using a 
DispatcherTimer that updates a few times per second. 

WPF Software Rendering 

WPF renders synchronously on the Ul thread in software in the following situations. 

• Printing 

• BitmapEffect 

• RenderTargetBitmap 

When one of these situations occurs, the rendering system calls the CopyBackBuffer method to copy the hardware 
buffer to software. The default implementation calls the GetRenderiargetoata method with your surface. Because 
this call occurs outside of the Lock/Unlock pattern, it may fail. In this case, the CopyBackBuffer method returns 
null and no image is displayed. 

You can override the CopyBackBuffer method, call the base implementation, and if it returns null , you can return 
a placeholder BitmapSource. 

You can also implement your own software rendering instead of calling the base implementation. 


NOTE 

If WPF is rendering completely in software, DSDImage is not shown because WPF does not have a front buffer. 


See also 

• DBDImage 

• Performance Considerations for Direct3D9 and WPF Interoperability 

• Walkthrough: Creating Direct3D9 Content for Hosting in WPF 

• Walkthrough: Hosting Direct3D9 Content in WPF 









Performance Considerations for Direct3D9 and WPF 
Interoperability 

1/24/2020 • 4 minutes to read i Edit Online 


You can host DirectsD9 content by using the DSDImage class. Hosting DirectsD9 content can affect the 
performance of your application. This topic describes best practices to optimize performance when hosting 
DirectSD9 content in a Windows Presentation Foundation (WPF) application. These best practices include how to 
use DSDImage and best practices when you are using Windows Vista, Windows XR and multi-monitor displays. 


NOTE 

For code examples that demonstrate these best practices, see WPF and Direct3D9 Interoperation. 


Use DSDImage Sparingly 

DirectsD9 content hosted in a DSDImage instance does not render as fast as in a pure DirectSD application. 
Copying the surface and flushing the command buffer can be costly operations. As the number of DSDImage 
instances increases, more flushing occurs, and performance degrades. Therefore, you should use DSDImage 
sparingly. 

Best Practices on Windows Vista 

For best performance on Windows Vista with a display that is configured to use the Windows Display Driver 
Model (WDDM), create your DirectSD9 surface on an iDir’ectBDDeviceSEx device. This enables surface sharing. The 
video card must support the d3ddevcaps2_can_stretchrect_from_textures and d3dcaps2_canshareresource driver 
capabilities on Windows Vista. Any other settings cause the surface to be copied through software, which reduces 
performance significantly. 


NOTE 

If Windows Vista has a display that is configured to use the Windows XP Display Driver Model (XDDM), the surface is always 
copied through software, regardless of settings. With the proper settings and video card, you will see better performance on 
Windows Vista when you use the WDDM because surface copies are performed in hardware. 


Best Practices on Windows XP 

For best performance on Windows XR which uses the Windows XR Display Driver Model (XDDM), create a 
lockable surface that behaves correctly when the iDirect3DSur’face9: rcetoc method is called. Internally, the 
BitBit method transfers the surface across devices in hardware. The Getoc method always works on XRGB 
surfaces. However, if the client computer is running Windows XR with SR3 or SR2, and if the client also has the 
hotfix for the layered-window feature, this method only works on ARGB surfaces. The video card must support the 
D3DDEVCAPS2_CAN_STRETCHRECT_FR0M_TEXTURES driver Capability. 

A 16-bit desktop display depth can significantly reduce performance. A 32-bit desktop is recommended. 

If you are developing for Windows Vista and Windows XR test the performance on Windows XR Running out of 
video memory on Windows XP is a concern. In addition, DSDImage on Windows XP uses more video memory and 
bandwidth than Windows Vista WDDM, due to a necessary extra video memory copy. Therefore, you can expect 












performance to be worse on Windows XP than on Windows Vista for the same video hardware. 


NOTE 

XDDM is available on both Windows XP and Windows Vista; however, WDDM is available only on Windows Vista. 


General Best Practices 

When you create the device, use the d3DCREATE_multithreaded creation flag. This reduces performance, but the 
WPF rendering system calls methods on this device from another thread. Be sure to follow the locking protocol 
correctly, so that no two threads access the device at the same time. 

If your rendering is performed on a WPF managed thread, it is strongly recommended that you create the device 
with the D3DCREATE_FPU_PRESERVE Creation flag. Without this setting, the DSD rendering can reduce the accuracy of 
WPF double-precision operations and introduce rendering issues. 

Tiling a DSDImage is fast, unless you tile a non-pow2 surface without hardware support, or if you tile a 
DrawingBrush or VisualBrush that contains a DSDImage. 

Best Practices for Multi-Monitor Displays 

If you are using a computer that has multiple monitors, you should follow the previously described best practices. 
There are also some additional performance considerations for a multi-monitor configuration. 

When you create the back buffer, it is created on a specific device and adapter, but WPF may display the front 
buffer on any adapter. Copying across adapters to update the front buffer can be very expensive. On Windows 
Vista that is configured to use the WDDM with multiple video cards and with an iDirect3DDevice9Ex device, if the 
front buffer is on a different adapter but still the same video card, there is no performance penalty. However, on 
Windows XP and the XDDM with multiple video cards, there is a significant performance penalty when the front 
buffer is displayed on a different adapter than the back buffer. For more information, see WPF and Direct3D9 
Interoperation. 

Performance Summary 

The following table shows performance of the front buffer update as a function of operating system, pixel format, 
and surface lockability. The front buffer and back buffer are assumed to be on the same adapter. Depending on the 
adapter configuration, hardware updates are generally much faster than software updates. 


SURFACE PIXEL 

FORMAT 

WINDOWS VISTA, 

WDDM AND 9EX 

OTHER WINDOWS 

VISTA 

CONFIGURATIONS 

WINDOWS XP SP3 OR 

SP2 W/ HOTFIX 

WINDOWS XP SP2 

D3DFMT_X8R8G8B8 
(not lockable) 

Hardware Update 

Software Update 

Software Update 

Software Update 

D3DFMT_X8R8G8B8 

(lockable) 

Hardware Update 

Software Update 

Hardware Update 

Hardware Update 

D3DFMT_A8R8G8B8 
(not lockable) 

Hardware Update 

Software Update 

Software Update 

Software Update 

D3DFMT_A8R8G8B8 

(lockable) 

Hardware Update 

Software Update 

Hardware Update 

Software Update 
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Walkthrough: Creating Direct3D9 Content for 
Hosting in WPF 

1/24/2020 • 13 minutes to read i Edit Online 


This walkthrough shows how to create DirectsD9 content that is suitable for hosting in a Windows Presentation 
Foundation (WPF) application. For more information on hosting DirectsD9 content in WPF applications, see WPF 
and Direct3D9 Interoperation. 

In this walkthrough, you perform the following tasks: 

• Create a Direct3D9 project. 

• Configure the Direct3D9 project for hosting in a WPF application. 

When you are finished, you will have a DLL that contains DirectsD9 content for use in a WPF application. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio 2010. 

• DirectX SDK 9 or later. 

Creating the Direct3D9 Project 

The first step is to create and configure the DirectsD9 project. 

To create the Direct3D9 project 

1. Create a new Win32 Project in C + + named DSDContent . 

The Win32 Application Wizard opens and displays the Welcome screen. 

2. Click Next. 

The Application Settings screen appears. 

3. In the Application type; section, select the DLL option. 

4. Click Finish. 

The DSDContent project is generated. 

5. In Solution Explorer, right-click the DSDContent project and select Properties. 

The DSDContent Property Pages dialog box opens. 

6. Select the C/C + + node. 

7. In the Additional Include Directories field, specify the location of the DirectX include folder. The default 
location for this folder is %ProgramFiles%\Microsoft DirectX SDK (Ke/'5/o/7)\lnclude. 

8. Double-click the Linker node to expand it. 

9. In the Additional Library Directories field, specify the location of the DirectX libraries folder. The default 
location for this folder is %ProgramFiles%\Microsoft DirectX SDK (Ke/'5/o/7)\Lib\x86. 





10. Select the Input node. 

11. In the Additional Dependencies field, add the dsdg.iib and d3dx9.iib files. 

12. In Solution Explorer, add a new module definition file (.def) named DSDContent.def to the project. 

Creating the Direct3D9 Content 

To get the best performance, your DirectsD9 content must use particular settings. The following code shows how 
to create a DirectsD9 surface that has the best performance characteristics. For more information, see 
Performance Considerations for DirectSD9 and WPF Interoperability. 

To create the Direct3D9 content 

1. Using Solution Explorer, add three C+ + classes to the project named the following. 

CRendenen (with virtual destructor) 

CRendenerManager 

CTniangleRendener 

2. Open Renderer.h in the Code Editor and replace the automatically generated code with the following code. 


tpnagma once 

class CRendenen 

{ 

public: 

vintual ~CRendenen(); 

HRESULT CheckDeviceStateO; 

HRESULT CneateSunface(UINT uWidth, UINT uHeightj bool fUseAlphaj UINT m_uNumSamples); 
vintual HRESULT Renden() = 0; 

IDinect3DSunface9 *GetSunfaceNoRef() { netunn m_pd3dRTS; } 

pnotected: 

CRendenenO; 

vintual HRESULT Init(IDinect3D9 *pD3Dj IDinect3D9Ex *pD3DEXj HWND hwnd, UINT uAdapten); 

IDinect3DDevlce9 *m_pd3dDevice; 

IDinect3DDevice9Ex *m_pd3dDeviceEx; 

IDinect3DSunface9 *m_pd3dRTS; 

}; 

S. Open Renderer.cpp in the Code Editor and replace the automatically generated code with the following 
code. 

//+ - 

// 

// CRendenen 

// 

// An abstnact base class that cneates a device and a tanget nenden 

// sunface. Denive fnom this class and ovennide Init() and Renden() 

// to do youn own nendening. See CTniangleRendenen fon an example. 

// --- 











#include "StdAfx.h" 


//+ - 

// 

// Member: 

// CRenderer ctor 

// 

// - 

CRenderer::CRenderer() : m_pd3dDevice(MULL)j m_pd3dDeviceEx(NULL)j m_pd3dRTS(NULL) 

{ 

} 

//+ --- 

// 

// Member: 

// CRenderer dtor 

// 

// -- 

CRenderer::~CRenderer() 

{ 

SAFE_RELEASE(m_pd3dDevice); 

SAFE_RELEASE(m_pd3dDeviceEx); 

SAFE_RELEASE(m_pd3dRTS); 

} 

//+ - 

// 

// Member: 

// CRenderer::CheckDeviceState 

// 

// Synopsis: 

// Returns the status of the device. 9Ex devices are a special case because 

// TestCooperativeLevel() has been deprecated in 9Ex. 

// 

// -- 

HRESULT 

CRenderer::CheckDeviceState() 

{ 

if (m_pd3dDeviceEx) 

{ 

return m_pd3dDeviceEx->CheckDeviceState(NULL)j 

} 

else if (m_pd3dDevice) 

{ 

return m_pd3dDevice->TestCooperativeLevel(); 

} 

else 

{ 

return D3DERR_DEVICEL0ST; 

} 

} 

//+ - 

// 

// Member: 

// CRenderer::CreateSurface 

// 

// Synopsis: 

// Creates and sets the render target 

// 

// ---- 

HRESULT 

CRenderer::CreateSurface(UINT uWidthj UINT uHeight, bool fUseAlpha, UINT m_uNumSamples) 

{ 

HRESULT hr = S_OK; 

SAFE_RELEASE(m_pd3dRTS); 










IFC(m_pd3dDevice->CreateRenderTarget( 

uWidthj 

uHeight^ 

fUseAlpha ? D3DFHT_A8R8G8B8 : D3DFMT_X8R8G8B8, 
static_cast<D3DMULTISAMPLE_TYPE>(m_uNumSamples)j 
0. 

tn_pd3dDeviceEx ? EALSE : TRUE, // Lockable RT required for good XP perf 
&m_pd3dRTS, 

NULL 

)); 

IPC(m_pd3dDevice->SetRenderTarget(0, m_pd3dRTS)); 

Cleanup: 

return hr; 

} 

//+ - 

// 

// Member: 

// CRenderer::Init 

// 

// Synopsis: 

// Creates the device 

// 

// - 

HRESULT 

CRenderer::Init(IDirect3D9 *pD3D, IDirect3D9Ex *pD3DEx, HWND hwnd, UINT uAdapter) 

{ 

HRESULT hr = S_OK; 

D3DPRESENT_PARAMETERS d3dpp; 

ZeroMemory(&d3dpp, sizeof(d3dpp)); 
d3dpp.Windowed = TRUE; 
d3dpp.BackBufferFormat = D3DFMT_UNKN0WN; 
d3dpp.BackBufferHeight = 1; 
d3dpp.BackBufferWidth = 1; 
d3dpp.SwapEffect = D3DSWAPEEFECT_DISCARD; 

D3DCAPS9 caps; 

DWORD dwVertexProcessing; 

IFC(pD3D->GetDeviceCaps(uAdapter, D3DDEVTYPE_HAL, &caps)); 

if ((caps.DevCaps & D3DDEVCAPS_HWTRANSE0RMANDLIGHT) == D3DDEVCAPS_HWTRANSF0RMANDLIGHT) 

{ 

dwVertexProcessing = D3DCREATE_HARDWARE_VERTEXPR0CESSING; 

} 

else 

{ 

dwVertexProcessing = D3DCREATE_S0FTWARE_VERTEXPR0CESSING; 

} 

if (pD3DEx) 

{ 

IDirect3DDevice9Ex *pd3dDevice = NULL; 

IPC(pD3DEx->CreateDeviceEx( 

uAdapter, 

D3DDEVTYPE_HAL, 

hwnd, 

dwVertexProcessing | D3DCREATE_MULTITHREADED | D3DCREATE_FPU_PRESERVE, 

&d3dpp, 

NULL, 

&m_pd3dDeviceEx 

)); 

IPC(m_pd3dDeviceEx->QueryInterface(_uuidof(IDirect3DDevice9), reinterpret_cast<void**> 

(&m_pd3dDevice))); 

} 

else 

{ 




asser't(pD3D); 


IFC(pD3D->CreateDevice( 

uAdapterj 

D3DDEVTYPE_HAL, 

hwndj 

dwVertexProcessing | D3DCREATE_MULTITHREADED | D3DCREATE_FPU_PRESERVE, 
&d3dppj 
&m_pd3dDevice 
)); 

} 

Cleanup: 

return hr; 

} 


4. Open RendererManager.h in the Code Editor and replace the automatically generated code with the 
following code. 


Spnagma once 

class CRendenen; 

class CRenderenManager 

{ 

public: 

static HRESULT Create(CRenderenManager ♦*ppManager)j 
~CRendererManager(); 

HRESULT EnsuneDevicesO; 

void SetSize(UINT uWidthj UINT uHeight); 
void SetAlpha(bool fUseAlpha); 
void SetNumDesiredSamples(UINT uNumSamples)j 
void SetAdapten(POINT screenSpacePoint); 

HRESULT GetBackBufferNoRef(IDinect3DSurface9 **ppSur'face)j 

HRESULT RenderO; 

private: 

CRendererManagerO; 

void CleanupInvalidDevices(); 

HRESULT EnsureRenderersO; 

HRESULT EnsureHWNDO; 

HRESULT EnsureD3D0bjects(); 

HRESULT TestSurfaceSettingsO; 
void DestroyResourcesO; 

IDirect3D9 *m_pD3D; 

IDirect3D9Ex *m_pD3DEx; 

UINT m_cAdapters; 

CRenderer **m_rgRenderers; 

CRenderer *m_pCurrentRenderer; 

HWND m_hwnd; 

UINT m_uWidth; 

UINT m_uHeight; 

UINT m_uNumSamples; 

bool m_fUseAlpha; 

bool m_fSurfaceSettingsChanged; 


5. Open RendererManager.cpp in the Code Editor and replace the automatically generated code with the 
following code. 

//+ -------- 

// 

// CRenderenManager 

// 

// Manages the list of CRenderers. Managed code pinvokes into this class 

// and this class forwards to the appropriate CRenderer. 

// 

// - 

#include "StdAfx.h" 

const static TCHAR szAppName[] = TEXT("D3DImageSample")j 

typedef HRESULT (WINAPI *DIRECT3DCREATE9EXFUNCTI0N)(UINT SDKVersion, IDirect3D9Ex**); 





// 

// Member: 

// CRendererManager ctor 

// 

// - 

CRendererManager::CRendererManager() 

m_pD3D(NULL), 

m_pD3DEx(NULL), 

m_cAdapters(0)j 

m_hwnd(NULL)j 

m_pCurrentRenderer(NULL)j 

m_rgRenderers(NULL)^ 

m_uWidth(1024)j 

m_uHeight(1024)j 

m_uNumSamples(0)j 

m_fUseAlpha(false)j 

m_fSurfaceSettingsChanged(true) 


//+ - 

// 

// Member: 

// CRendererManager dtor 

// 

// - 

CRendererManager::~CRendererManager() 

{ 

DestroyResources(); 

if (m_hwnd) 

{ 

DestroyWindow(m_hwnd); 
UnregisterClass(szAppNamej NULL); 

} 


//+ - 

// 

// Member: 

// CRendererManager::Create 

// 

// Synopsis: 

// Creates the manager 

// 

// - 

HRESULT 

CRendererManager::Create(CRendererManager **ppManager) 

{ 

HRESULT hr = S_OK; 

*ppManager = new CRendererManager(); 
IFCOOM(*ppManager); 

Cleanup: 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::EnsureRenderers 

// 

// Synopsis: 

// Makes sure the CRenderer objects exist 









// - 

HRESULT 

CRendenerManager: : EnsuneRenderersO 

{ 

HRESULT hr = S_OK; 

if (!m_rgRenderers) 

{ 

IFC(EnsureHWND()); 
assert(m_cAdapters); 

m_rgRenderers = new CRenderer*[m_cAdapters]j 
IFCOOM(m_rgRenderers); 

ZeroMemory(m_rgRendererSj m_cAdapters * sizeof(m_rgRenderers[0]))j 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

IFC(CTriangleRenderer::Create(m_pD3D, m_pD3DEXj m_hwndj ij &m_rgRenderers[i])) 

} 

// Default to the default adapter 
tn_pCurrentRenderer = m_rgRenderers[0] j 

} 

Cleanup: 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::EnsureHWND 

// 

// Synopsis: 

// Hakes sure an HWND exists if we need it 

// 

// - 

HRESULT 

CRendererManager::EnsureHWND() 

{ 

HRESULT hr = S_OK; 

if (!m_hwnd) 

{ 

WNDCLASS wndclass; 

wndclass.style = CS_HREDRAW | CS_VREDRAW; 
wndclass.IpfnWndProc = DefWindowProc; 
wndclass.cbClsExtra = 0; 
wndclass.cbWndExtra = 0; 
wndclass.hinstance = NULL; 

wndclass.hicon = LoadIcon(NULLj IDI_APPLICATION); 

wndclass.hCursor = LoadCursor(NULLj IDC_ARROW); 

wndclass.hbrBackground = (HBRUSH) GetStockObject (WHITE_BRUSH); 

wndclass.IpszMenuName = NULL; 

wndclass.IpszClassName = szAppName; 

if (!RegisterClass(&wndclass)) 

{ 

IFC(E_FAIL); 

} 

m_hwnd = CreateWindow(szAppNamej 

TEXT("D3DImageSample "), 

WS_OVERLAPPEDWINDOW, 

0, // Initial X 

0, // Initial Y 

0, II Width 






// Heignt 


NULL, 

NULL, 

NULL, 

NULL); 

} 

Cleanup: 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::EnsureDBDObjects 

// 

// Synopsis: 

// Hakes sure the D3D objects exist 

// 

// - 

HRESULT 

CRendererManager::EnsureD3DObjects() 

{ 

HRESULT hr = S_OK; 

HMODULE hD3D = NULL; 
if (!m_pD3D) 

{ 

hD3D = LoadLibrary(TEXT("d3d9.dll")); 

DIRECT3DCREATE9EXFUNCTION pfnCreate9Ex = (DIRECT3DCREATE9EXFUNCTION)GetProcAddress(hD3D, 
"Direct3DCreate9Ex"); 

if (pfnCreate9Ex) 

{ 

IFC((*pfnCreate9Ex)(D3D_SDK_VERSION, &m_pD3DEx)); 

IFC(m_pD3DEx->QueryInterface(_uuidof(IDirect3D9), reinterpret_cast<void **>(&m_pD3D))) 

} 

else 

{ 

m_pD3D = Direct3DCreate9(D3D_SDK_VERSION); 
if (!m_pD3D) 

{ 

IFC(E_FAIL); 

} 

} 

m_cAdapters = m_pD3D->GetAdapterCount(); 

} 

Cleanup: 

if (hD3D) 

{ 

FreeLibrary(hD3D); 

} 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::CleanupInvalidDevices 

// 

// Synopsis: 

// Checks to see if any devices are bad and if so, deletes all resources 

// 

// We could delete resources and wait for D3DERR_DEVICEN0TRESET and reset 

// the devices, but if the device is lost because of an adapter order 

// change then our existing D3D objects would have stale adapter 

// information. We'll delete everything to be safe rather than sorry. 





// 

// - 

void 

CRendenenManager::CleanupInvalidDevices() 

{ 

for (UINT i = 0; i < m_cAdapter's; ++i) 

{ 

If (FAILED(m_rgRender'er's[i]->CheckDeviceState())) 

{ 

DestroyResourcesO; 

break; 

} 

} 

} 

//+ - 

// 

// Member: 

// CRendererManager::GetBackBufferNoRef 

// 

// Synopsis: 

// Returns the surface of the current tenderer without adding a reference 

// 

// This can return NULL if we're in a bad device state. 

// 

// ----- 

HRESULT 

CRendererManager::GetBackBufferNoRef(IDirect3DSurface9 **ppSurface) 

{ 

HRESULT hr = S_OK; 

// Make sure we at least return NULL 
*ppSurface = NULL; 

CleanupInvalidDevicesO; 

IFC(EnsureD3D0bjects()); 

// 

// Even if we never render to another adapter^ this sample creates devices 
// and resources on each one. This is a potential waste of video memoryj 
// but it guarantees that we won't have any problems (e.g. out of video 
// memory) when switching to render on another adapter. In your own code 
// you may choose to delay creation but you'll need to handle the issues 
// that come with it. 

// 

IFC(EnsureRenderers()); 

if (m_fSurfaceSettingsChanged) 

{ 

if (FAILED(TestSurfaceSettings())) 

{ 

IFC(E_FAIL); 

} 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

IFC(m_rgRenderers[i]->CreateSurface(m_uWidth, m_uHeightj m_fUseAlpha, m_uNumSamples)) 

} 

m_fSurfaceSettingsChanged = false; 

} 

if (m_pCurrentRenderer) 

{ 

*ppSurface = m_pCurrentRenderer->GetSurfaceNoRef(); 

} 





Cleanup: 

// If we failed because of a bad device^ ignore the failure for now and 
// we'll clean up and try again next time, 
if (hr == D3DERR_DEVICEL0ST) 

{ 

hr = S_OK; 

} 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::TestSurfaceSettings 

// 

// Synopsis: 

// Checks to see if our current surface settings are allowed on all 

// adapters. 

// 

// ----- 

HRESULT 

CRendererManager::TestSurfaceSettings() 

{ 

HRESULT hr = S_OK; 

D3DF0RMAT fmt = m_fUseAlpha ? D3DFMT_A8R8G8B8 : D3DFMT_X8R8G8B8; 

// 

// We test all adapters because because we potentially use all adapters. 

// But even if this sample only rendered to the default adapter^ you 
// should check all adapters because WPF may move your surface to 
// another adapter for you! 

// 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

// Can we get HW rendering? 

IFC(m_pD3D->CheckDeviceType( 

i. 

D3DDEVTYPE_HAL, 

D3DFMT_X8R8G8B8, 

fmt^ 

TRUE 

)); 

// Is the format okay? 

IFC(m_pD3D->CheckDeviceFormat( 

i. 

D3DDEVTYPE_HAL, 

D3DFMT_X8R8G8B8, 

D3DUSAGE_RENDERTARGET | D3DUSAGE_DYNAMIC, // We'll use dynamic when on XP 
D3DRTYPE_SURFACE, 
fmt 
)); 

// D3DImage only allows multisampling on 9Ex devices. If we can't 
// multisamplej overwrite the desired number of samples with 0. 
if (m_pD3DEx && m_uNumSamples > 1) 

{ 

assert(m_uNumSamples <= 16); 

if (FAILED(m_pD3D->CheckDeviceMultiSampleType( 
i, 

D3DDEVTYPE_HAL, 

fmt j 

TRUE, 

static_cast<D3DMULTISAMPLE_TYPE>(m_uNumSamples), 

NULL 




))) 

{ 

m_uNumSamples = 0; 

} 

} 

else 

{ 

m_uNumSamples = 0; 

} 

} 

Cleanup: 

return hr; 

} 

//+ - 

// 

// Member: 

// CRendererManager::DestroyResources 

// 

// Synopsis: 

// Delete all D3D resources 

// 

// - 

void 

CRendererManager::DestroyResources() 

{ 

SAFE_RELEASE(m_pD3D); 

SAFE_RELEASE(m_pD3DEx); 

for (DINT i = 0; i < m_cAdapters; ++i) 

{ 

delete m_rgRenderers[i]; 

} 

delete [] m_rgRenderers; 
m_rgRenderers = NULL; 

m_pCurrentRenderer = NULL; 
m_cAdapters = 0; 

m_fSurfaceSettingsChanged = true; 

} 

//+ - 

// 

// Member: 

// CRendererManager::SetSize 

// 

// Synopsis: 

// Update the size of the surface. Next render will create a new surface. 

// 

// - 

void 

CRendererManager::SetSize(UINT uWidth, UINT uHeight) 

{ 

if (uWidth != m_uWidth || uHeight != m_uHeight) 

{ 

m_uWidth = uWidth; 
m_uHeight = uHeight; 
m_fSurfaceSettingsChanged = true; 

} 

} 

//+ - 

// 

// Member: 

// CRendererManager::SetAlpha 

// 

// SvnoDsis: 







// Update the format of the surface. Next render will create a new surface. 

// 

// - 

void 

CRendererManager::SetAlpha(bool fUseAlpha) 

{ 

if (fUseAlpha != m_fUseAlpha) 

{ 

m_fUseAlpha = fUseAlpha; 
m_fSurfaceSettingsChanged = true; 

} 

} 

//+ - 

// 

// Member: 

// CRendererManager::SetNumDesiredSamples 

// 

// Synopsis: 

// Update the MSAA settings of the surface. Next render will create a 

// new surface. 

// 

// - 

void 

CRendererManager::SetNumDesiredSamples(UINT uNumSamples) 

{ 

if (m_uNumSamples != uNumSamples) 

{ 

m_uNumSamples = uNumSamples; 
m_fSurfaceSettingsChanged = true; 

} 


//+ - 

// 

// Member: 

// CRendererManager::SetAdapter 

// 

// Synopsis: 

// Update the current renderer. Next render will use the new renderer. 

// 

// - 

void 

CRendererManager::SetAdapter(POINT screenSpacePoint) 

{ 

CleanupInvalidDevicesO; 

// 

// After CleanupInvalidDeviceSj we may not have any D3D objects. Rather than 
// recreate them here, ignore the adapter update and wait for render to recreate. 
// 

if (m_pD3D && m_rgRenderers) 

{ 

HMONITOR hMon = MonitorFromPoint(screenSpacePoint, MONITOR_DEFAULTTONULL); 

for (UINT i = 0; i < m_cAdapters; ++i) 

{ 

if (hMon == m_pD3D->GetAdapterMonitor(i)) 

{ 

m_pCurrentRenderer = m_rgRenderers[i]; 
break; 

} 

} 

} 

} 

//+ - 

/ / 








/ / 

// Member: 

// CRendererManager::Render 

// 

// Synopsis: 

// Forward to the current renderer 

// 

// --- 

HRESULT 

CRendererManager::Render() 

{ 

return m_pCurrentRenderer ? m_pCurrentRenderer->Render() : S_OKj 

} 


6. Open TriangleRenderer.h in the Code Editor and replace the automatically generated code with the following 
code. 


#pragma once 

class CTriangleRenderer : public CRenderer 

{ 

public: 

static HRESULT Create(IDirect3D9 *pD3Dj IDirect3D9Ex *pD3DEx, HWND hwndj UINT uAdapter^ CRenderer 
**ppRenderer); 

~CTriangleRenderer(); 

HRESULT RenderO; 

protected: 

HRESULT Init(IDirect3D9 *pD3D, IDirect3D9Ex *pD3DEx, HWND hwnd, UINT uAdapter); 
private: 

CTriangleRenderer 0; 

IDirect3D\/ertexBuffer9 *m_pd3dVB; 

}; 


7. Open TriangleRenderer.cpp in the Code Editor and replace the automatically generated code with the 
following code. 

//+ -- 

// 

// CTriangleRenderer 

// 

// Subclass of CRenderer that renders a single^ spinning triangle 

// 

// - 

#include "StdAfx.h" 

struct CUSTOMVERTEX 

{ 

FLOAT X, y, z; 

DWORD color; 


#define D3DFVF_CUST0MVERTEX (D3DFVF_XYZ | D3DFVF_DIFFUSE) 

//+ --- 

// 

// Member: 

// CTriangleRenderer ctor 

// 

// --- 








CTriangleRendener: :CTriangleRenderer() : CRenderer(), m_pd3dVB(NLILL) 

{ 

} 

//+ - 

// 

// Member: 

// CTriangleRendener dtor 

// 

// - 

CTriangleRendener::~CTriangleRenderer() 

{ 

SAFE_RELEASE(m_pd3dVB); 

} 

//+ - 

// 

// Member: 

// CTriangleRendener::Create 

// 

// Synopsis: 

// Creates the renderer 

// 

// --- 

HRESULT 

CTriangleRendener::Create(IDirect3D9 *pD3D, IDirect3D9Ex *pD3DEx, HWND hwndj UINT uAdapter^ CRenderer 
**ppRenderer) 

{ 

HRESULT hr = S_OK; 

CTriangleRendener *pRenderer = new CTriangleRenderer(); 

IFCOOM(pRenderer); 

IFC(pRenderer->Init(pD3D, pD3DEXj hwnd, uAdapter)); 

*ppRenderer = pRenderer; 
pRenderer = NULL; 

Cleanup: 

delete pRenderer; 
return hr; 

} 

//+ - 

// 

// Member: 

// CTriangleRendener::Init 

// 

// Synopsis: 

// Override of CRenderer::Init that calls base to create the device and 

// then creates the CTriangleRenderer-specific resources 

// 

// - 

HRESULT 

CTriangleRendener::Init(IDirect3D9 *pD3Dj IDirect3D9Ex *pD3DEXj HWND hwndj UINT uAdapter) 

{ 

HRESULT hr = S_OK; 

D3DXMATRIXA16 matVieWj matProj; 

D3DXVECTOR3 vEyePt(0.0f, 0.0f,-5.0f); 

D3DXVECTOR3 vLool<atPt(0.0f, 0.0f, 0.0f); 

D3DXVECTOR3 vUpVec(0.0f, 1.0f, 0.0f); 

// Call base to create the device and render target 
IFC(CRenderer::Init(pD3Dj pD3DEXj hwnd, uAdapter)); 

// Set up the VB 
CUSTOMVERTEX vertices[] = 

{ 








{ 

-1.0f, 

-1.0f, 

0.0f, 

0xffff0000, 

// X, y, z, color 

{ 

1.0f, 

-1.0f, 

0.0f, 

0xff00ff00j 


{ 

0.0f, 

1.0f, 

0.0f, 

0xff00ffffj 



}; 

IFC(m_pd3dDevice->CreateVer'texBuffer(sizeof(vertices), 0, D3DFVF_CUST0MVERTEX, D3DP00L_DEFAULT, 
&m_pd3dVB, NULL)); 

void *pVertices; 

IFC(m_pd3dVB->Lock(0, sizeof(vertices), SpVertices, 0)); 
memcpy(pVertices, vertices, sizeof(vertices)); 
m_pd3dVB->Unlock(); 

// Set up the camera 

D3DXMatrixLookAtLH(&mat\/iew, SvEyePt, &vLookatPt, &vUpVec); 
IFC(m_pd3dDevice->SetTransform(D3DTS_VIEW, SmatView)); 

D3DXMatrixPerspectiveFovLH(&matProj, D3DX_PI / 4, 1.0f, 1.0f, 100.0f); 
IFC(m_pd3dDevice->SetTransform(D3DTS_PR03ECTI0N, &matProj)); 

// Set up the global state 

IFC(m_pd3dDevice->SetRenderState(D3DRS_CULLMODE, D3DCULL_N0NE)); 
IFC(m_pd3dDevice->SetRenderState(D3DRS_LIGHTING, FALSE)); 

IFC(m_pd3dDevice->SetStreamSource(0, m_pd3dVB, 0, sizeof(CUSTOMVERTEX))); 
IFC(m_pd3dDevice->SetFVF(D3DFVF_CUSTOMVERTEX)); 

Cleanup: 

return hr; 

} 

//+ --- 

// 

// Member: 

// CTriangleRenderer::Render 

// 

// Synopsis: 

// Renders the rotating triangle 

// 

// - 

HRESULT 

CTriangleRenderer::Render() 

{ 

HRESULT hr = S_OK; 

D3DXMATRIXA16 matWorld; 

IFC(m_pd3dDevice->BeginScene()); 

IFC(m_pd3dDevice->Clear( 

0, 

NULL, 

D3DCLEAR_TARGET, 

D3DC0L0R_ARGB(128, 0, 0, 128), // NOTE: Premultiplied alpha! 

1.0f, 

0 

)); 

// Set up the rotation 

UINT iTime = GetTickCount() % 1000; 

FLOAT fAngle = iTime * (2.0f * D3DX_PI) / 1000.0f; 

D3DXMatrixRotationY(&matWorld, fAngle); 

IFC(m_pd3dDevice->SetTransform(D3DTS_WORLD, &matWorld)); 

IFC(m_pd3dDevice->DrawPrimitive(D3DPT_TRIANGLELIST, 0, 1)); 

IFC(m_pd3dDevice->EndScene()); 

Cleanup: 

return hr; 

} 




8. Open stdafx.h in the Code Editor and replace the automatically generated code with the following code. 


// stdafx.h : include file for standard system include files, 

// or project specific include files that are used frequently, but 
// are changed infrequently 
// 

#pragma once 

#define WIM32_LEAN_AND_MEAIM // Exclude rarely-used stuff from Windows headers 

// Windows Header Files: 

#include <windows.h> 

#include <d3d9.h> 

#include <d3dx9.h> 

#include <assert.h> 

#include "RendererManager.h" 

#include "Renderer.h" 

#include "TriangleRenderer.h" 

#define IFC(x) { hr = (x); if (FAILED(hr)) goto Cleanup; } 

#define IFCOOM(x) { if ((x) == NULL) { hr = E_OUTOFMEMORY; IFC(hr); } } 

#define SAFE_RELEASE(x) { if (x) { x->Release(); x = NULL; } } 


9. Open dllmain.cpp in the Code Editor and replace the automatically generated code with the following code. 

// dllmain.cpp : Defines the entry point for the DLL application. 

#include "stdafx.h" 

BOOL APIENTRY DllMain( HMODULE hModule, 

DWORD ul_reason_for_call, 

LPVOID IpReserved 

) 

{ 

switch (ul_reason_for_call) 

{ 

case DLL_PROCESS_ATTACH: 
case DLL_THREAD_ATTACH: 
case DLL_THREAD_DETACH: 
case DLL_PROCESS_DETACH: 
break; 

} 

return TRUE; 

} 

static CRendererManager *pManager = NULL; 

static HRESULT EnsureRendererManager() 

{ 

return pHanager ? S_OK : CRendererManager::Create(&pManager); 

} 

extern "C" HRESULT WINAPI SetSize(UINT uWidth, UINT uHeight) 

{ 

HRESULT hr = S_OK; 

IFC(EnsureRendererManager()); 

pManager->SetSize(uWidth, uHeight); 

Cleanup: 

return hr; 


} 



extern "C" HRESULT WINAPI SetAlpha(BOOL fUseAlpha) 

{ 

HRESULT hr = S_OK; 

IFC(EnsureRendererManager()); 

pManager->SetAlpha(!IfUseAlpha); 

Cleanup: 

return hr; 

} 

extern "C" HRESULT WINAPI SetNumDesiredSamples(UINT uNumSamples) 

{ 

HRESULT hr = S_OK; 

IFC(EnsureRendererManager()); 

pManager->SetNumDesiredSamples(uNumSamples); 

Cleanup: 

return hr; 

} 

extern "C" HRESULT WINAPI SetAdapter(POINT screenSpacePoint) 

{ 

HRESULT hr = S_OK; 

IFC(EnsureRendererManager()); 

pManager->SetAdapter(screenSpacePoint); 

Cleanup: 

return hr; 

} 

extern "C" HRESULT WINAPI GetBackBufferNoRef(IDirect3DSurface9 **ppSurface) 

{ 

HRESULT hr = S_OK; 

IFC(EnsureRendererManager()); 

IFC(pManager->GetBackBufferNoRef(ppSurface)); 

Cleanup: 

return hr; 

} 

extern "C" HRESULT WINAPI Render() 

{ 

assert(pHanager); 
return pManager->Render(); 

} 

extern "C" void WINAPI Destroy() 

{ 

delete pManager; 
pManager = NULL; 

} 

10. Open DBDContent.def in the code editor. 

11. Replace the automatically generated code with the following code. 


LIBRARY "DBDContent" 

EXPORTS 

SetSize 

SetAlpha 

SetNumDesinedSamples 

SetAdapter 

GetBackBufferNoRef 

Render 

Destroy 


12. Build the project. 

Next Steps 

• Host the Direct3D9 content in a WPF application. For more information, see Walkthrough: Hosting Direct3D9 
Content in WPF. 

See also 

• D3Dlmage 

• Performance Considerations for Direct3D9 and WPF Interoperability 

• Walkthrough: Hosting Direct3D9 Content in WPF 
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This walkthrough shows how to host DirectsD9 content in a Windows Presentation Foundation (WPF) application. 
In this walkthrough, you perform the following tasks: 

• Create a WPF project to host the DirectSDO content 

• Import the Direct3D9 content. 

• Display the Direct3D9 content by using the DSDImage class. 

When you are finished, you will know how to host DirectsD9 content in a WPF application. 

Prerequisites 

You need the following components to complete this walkthrough: 

• Visual Studio. 

• DirectX SDK 9 or later. 

• A DLL that contains DirectsD9 content in a WPF-compatible format. For more information, see WPF and 
DirectsD9 Interoperation and Walkthrough: Creating DirectsD9 Content for Hosting in WPF. 

Creating the WPF Project 

The first step is to create the project for the WPF application. 

To create the WPF project 

Create a new WPF Application project in Visual C# named DSDHost . For more information, see Walkthrough: My 
first WPF desktop application. 

MainWindow.xamI opens in the WPF Designer. 

Importing the Direct3D9 Content 

You import the Direct3D9 content from an unmanaged DLL by using the Diiimport attribute. 

To import Direct3D9 content 

1. Open MainWindow.xaml.cs in the Code Editor. 

2. Replace the automatically generated code with the following code. 

using System; 

using System.Collections.Generic; 
using System.Linq; 
using System.Text; 
using System.Windows; 
using System.Windows.Controls; 
using System.Windows.Data; 
using System.Windows.Documents; 
using System.Windows.Input; 
using System.Windows.Interop; 
using System.Windows.Media; 
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using System.Windows.Navigation; 
using System.Windows.Shapes; 
using System.Windows.Threading; 
using System.Runtime.InteropServices; 
using System.Security.Permissions; 

namespace DBDHost 

{ 

public partial class MainWindow : Window 

{ 

public MainWindowO 

{ 

InitializeComponent(); 

// Set up the initial state for the DSDImage. 

HRESULT.Check(SetSize(512, 512)); 

HRESULT.Check(SetAlpha(false)); 

HRESULT.Check(SetNumDesiredSamples(4)); 

// 

// Optional: Subscribing to the IsFrontBufferAvailableChanged event. 

// 

// If you don't render every frame (e.g. you only render in 
// reaction to a button click)^ you should subscribe to the 
// IsFrontBufferAvailableChanged event to be notified when rendered content 
// is no longer being displayed. This event also notifies you when 
// the DBDImage is capable of being displayed again. 

// For example, in the button click case, if you don't render again when 
// the IsFrontBufferAvailable property is set to true, your 
// DBDImage won't display anything until the next button click. 

// 

// Because this application renders every frame, there is no need to 
// handle the IsFrontBufferAvailableChanged event. 

// 

CompositionTarget.Rendering += new EventFlandler(CompositionTarget_Rendering); 

// 

// Optional: Multi-adapter optimization 

// 

// The surface is created initially on a particular adapter. 

// If the WPF window is dragged to another adapter, WPF 
// ensures that the DBDImage still shows up on the new 
// adapter. 

// 

// This process is slow on Windows XP. 

// 

// Performance is better on Vista with a 9Ex device. It's only 
// slow when the DBDImage crosses a video-card boundary. 

// 

// To work around this issue, you can move your surface when 
// the DBDImage is displayed on another adapter. To 
// determine when that is the case, transform a point on the 
// DBDImage into screen space and find out which adapter 
// contains that screen space point. 

// 

// When your DBDImage straddles two adapters, nothing 
// can be done, because one will be updating slowly. 

// 

_adapterTimer = new DispatcherTimer(); 

_adapterTimer.Tick += new EventFlandler(AdapterTimer_Tick); 

_adapterTimer.Interval = new TimeSpan(0, 0, 0, 0, 500); 

_adapterTimer.Start(); 

// 

// Optional: Surface resizing 

// 

// The DBDImage is scaled when WPF renders it at a size 


// ditterent trom tne natural size ot tne surface, it tne 
// DBDImage is scaled up significantly^ image quality 
// degrades. 

// 

// To avoid this^ you can either create a very large 
// texture initially, or you can create new surfaces as 
// the size changes. Below is a very simple example of 
// how to do the latter. 

// 

// By creating a timer at Render priority, you are guaranteed 
// that new surfaces are created while the element 
// is still being arranged. A 200 ms interval gives 
// a good balance between image quality and performance. 

// You must be careful not to create new surfaces too 

// frequently. Frequently allocating a new surface may 

// fragment or exhaust video memory. This issue is more 

// significant on XDDM than it is on WDDM, because WDDM 

// can page out video memory. 

// 

// Another approach is deriving from the Image class, 

// participating in layout by overriding the ArrangeOverride method, and 
// updating size in the overriden method. Performance will degrade 
// if you resize too frequently. 

// 

// Blurry DBDImages can still occur due to subpixel 
// alignments. 

// 

_sizeTimer = new DispatcherTimer(DispatcherPriority.Render); 

_sizeTimer.Tick += new EventFlandler(SizeTimer_Tick); 

_sizeTimer.Interval = new TimeSpan(0, 0, 0, 0, 200); 

_sizeTimer.Start(); 

} 

~MainWindow() 

{ 

Destroy(); 

} 

void AdapterTimer_Tick(object sender, EventArgs e) 

{ 

POINT p = new POINT(imgelt.PointToScreen(new Point(0, 0))); 
HRESULT.Check(SetAdapter(p)); 

} 

void SizeTimer_Tick(object sender, EventArgs e) 

{ 

// The following code does not account for RenderTransforms. 

// To handle that case, you must transform up to the root and 
// check the size there. 

// Given that the DBDImage is at 96.0 DPI, its Width and Height 
// properties will always be integers. ActualWidth/Height 
// may not be integers, so they are cast to integers, 
uint actualWidth = (uint)imgelt.ActualWidth; 
uint actualHeight = (uint)imgelt.ActualHeight; 
if ((actualWidth > 0 && actualHeight > 0) && 

(actualWidth != (uint)d3dimg.Width || actualHeight != (uint)d3dimg.Height)) 

{ 

HRESULT.Check(SetSize(actualWidth, actualHeight)); 

} 

} 

void CompositionTarget_Rendering(object sender, EventArgs e) 

{ 

RenderingEventArgs args = (RenderingEventArgs)e; 

// It's possible for Rendering to call back twice in the same frame 
// so only render when we haven't already rendered in this frame. 


if (dBdimg.IsFrontBuffenAvailable && _lastRender != args.RenderingTime) 

{ 

IntPtn pSurface = IntPtr.Zero; 

HRESLILT.Check(GetBackBufferNoRef(out pSurface)); 
if (pSurface != IntPtr.Zero) 

{ 

dBdimg.Lock(); 

// Repeatedly calling SetBackBuffer with the same IntPtr is 
// a no-op. There is no performance penalty. 

d3dimg.SetBackBuffer(D3DResourceType.IDirect3DSurface9j pSurface); 
HRESULT.Check(Render()); 

d3dimg.AddDirtyRect(new Int32Rect(0j 0, d3dimg.PixelWidthj d3dimg.PixelHeight)); 
d3dimg.Unlock(); 

_lastRender = args.RenderingTime; 

} 

} 

} 

DispatcherTimer _sizeTimer; 

DispatcherTimer _adapterTimer; 

TimeSpan _lastRender; 

// Import the methods exported by the unmanaged Direct3D content. 

[Dlllmport("D3DCode.dll")] 

static extern int GetBackBufferNoRef(out IntPtr pSurface); 

[Dlllmport("D3DCode.dll")] 

static extern int SetSize(uint widths uint height); 

[Dlllmport("D3DCode.dll")] 

static extern int SetAlpha(bool useAlpha); 

[Dlllmport("D3DCode.dll")] 

static extern int SetNumDesiredSamples(uint numSamples); 

[StructLayout(LayoutKind.Sequential)] 
struct POINT 
{ 

public POINT(Point p) 

{ 

X = (int)p.X; 
y = (int)p.Y; 

} 

public int x; 
public int y; 

} 

[Dlllmport("D3DCode.dll")] 

static extern int SetAdapter(POINT screenSpacePoint); 

[Dlllmport("D3DCode.dll")] 
static extern int Render(); 

[Dlllmport("D3DCode.dll")] 
static extern void DestroyO; 

} 

public static class HRESULT 

{ 

[SecurityPermissionAttribute(SecurityAction.Demandj Flags = 

SecurityPermissionFlag.UnmanagedCode)] 

public static void Check(int hr) 

{ 

Marshal. ThrowExceptionForFIR( hr); 


} 


} 


} 


Hosting the Direct3D9 Content 

Finally, use the DBDImage class to host the Direct3D9 content. 

To host the Directs D9 content 

1. In MainWindow.xaml, replace the automatically generated XAML with the following XAML. 

<Window x:Class="D3DHost.MainWindow" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http: //schemas. microsoft. com/winfx/2006/xaml" 
xmlns:i="clr-namespace:System.Windows.Interop;assembly=PresentationCore" 
Title="MainWindow" Height="300" Width="300" Background="PaleGoldenrod"> 

<Grid> 

<Image x:Name="imgelt"> 

<Image.Source> 

<i:D3DImage x:Name="d3dimg" /> 

</Image.Source) 

</Image> 

</Grid> 

</Window> 


2. Build the project. 

3. Copy the DLL that contains the Direct3D9 content to the bin/Debug folder. 

4. Press F5 to run the project. 

The Direct3D9 content appears within the WPF application. 

See also 

• D3Dlmage 

• Performance Considerations for Direct3D9 and WPF Interoperability 
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Achieving optimal application performance requires forethought in application design and an understanding of 
best practices for Windows Presentation Foundation (WPF) application development. The topics in this section 
provide additional information on building high performance WPF applications. 

In This Section 

Graphics Rendering Tiers 

Optimizing WPF Application Performance 

Walkthrough: Caching Application Data in a WPF Application 

Reference 

RenderCapability 

Tier 

PresentationTraceSources 

See also 

• Layout 

• Animation Tips and Tricks 
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A rendering tier defines a level of graphics hardware capability and performance for a device that runs a WPF 
application. 

Graphics Hardware 

The features of the graphics hardware that most impact the rendering tier levels are: 

• Video RAM The amount of video memory on the graphics hardware determines the size and number of 
buffers that can be used for compositing graphics. 

• Pixel Shader A pixel shader is a graphics processing function that calculates effects on a per-pixel basis. 
Depending on the resolution of the displayed graphics, there could be several million pixels that need to be 
processed for each display frame. 

• Vertex Shader A vertex shader is a graphics processing function that performs mathematical operations 
on the vertex data of the object. 

• Multitexture Support Multitexture support refers to the ability to apply two or more distinct textures 
during a blending operation on a 3D graphics object. The degree of multitexture support is determined by 
the number of multitexture units on the graphics hardware. 

Rendering Tier Definitions 

The features of the graphics hardware determine the rendering capability of a WPF application. The WPF system 
defines three rendering tiers: 

• Rendering Tier 0 No graphics hardware acceleration. All graphics features use software acceleration. The 
DirectX version level is less than version 9.0. 

• Rendering Tier 1 Some graphics features use graphics hardware acceleration. The DirectX version level is 
greater than or equal to version 9.0. 

• Rendering Tier 2 Most graphics features use graphics hardware acceleration. The DirectX version level is 
greater than or equal to version 9.0. 

The RenderCapability.Tier property allows you to retrieve the rendering tier at application run time. You use the 
rendering tier to determine whether the device supports certain hardware-accelerated graphics features. Your 
application can then take different code paths at run time depending on the rendering tier supported by the 
device. 

Rendering Tier 0 

A rendering tier value of 0 means that there is no graphics hardware acceleration available for the application on 
the device. At this tier level, you should assume that all graphics will be rendered by software with no hardware 
acceleration. This tier's functionality corresponds to a DirectX version that is less than 9.0. 


Rendering Tier 1 and Rendering Tier 2 




NOTE 

Starting in the .NET Framework 4, rendering tier 1 has been redefined to only include graphics hardware that supports 
DirectX 9.0 or greater. Graphics hardware that supports DirectX 7 or 8 is now defined as rendering tier 0. 


A rendering tier value of 1 or 2 nneans that most of the graphics features of WPF will use hardware acceleration if 
the necessary system resources are available and have not been exhausted. This corresponds to a DirectX version 
that is greater than or equal to 9.0. 

The following table shows the differences in graphics hardware requirements for rendering tier 1 and rendering 
tier 2: 


FEATURE 

TIER 1 TIER 2 

DirectX version 

Must be greater than or equal to 9.0. Must be greater than or equal to 9.0. 

Video RAM 

Must be greater than or equal to 60 Must be greater than or equal to 120 

MB. MB. 

Pixel shader 

Version level must greater than or Version level must greater than or 

equal to 2.0. equal to 2.0. 

Vertex shader 

No requirement. Version level must greater than or 

equal to 2.0. 

Multitexture units 

No requirement. Number of units must greater than or 

equal to 4. 


The following features and capabilities are hardware accelerated for rendering tier 1 and rendering tier 2 


FEATURE 

NOTES 

2D rendering 

Most 2D rendering is supported. 

3D rasterization 

Most 3D rasterization is supported. 

3D anisotropic filtering 

WPF attempts to use anisotropic filtering when rendering 3D 
content. Anisotropic filtering refers to enhancing the image 
quality of textures on surfaces that are far away and steeply 
angled with respect to the camera. 

3D MIP mapping 

WPF attempts to use MIP mapping when rendering 3D 
content. MIP mapping improves the quality of texture 
rendering when a texture occupies a smaller field of view in a 
Viewport3D. 

Radial gradients 

While supported, avoid the use of RadialGradientBrush on 
large objects. 

3D lighting calculations 

WPF performs per-vertex lighting, which means that a light 
intensity must be calculated at each vertex for each material 
applied to a mesh. 


Text rendering 


Subpixel font rendering uses available pixel shaders on the 
graphics hardware. 



The following features and capabilities are hardware accelerated only for rendering tier 2: 


FEATURE 

NOTES 

3D anti-aliasing 

3D anti-aliasing is supported only on operating systems that 
support Windows Display Driver Model (WDDM), such as 
Windows Vista and Windows 7. 


The following features and capabilities are not hardware accelerated: 


FEATURE 

NOTES 

Printed content 

All printed content is rendered using the WPF software 
pipeline. 

Rasterized content that uses RenderTargetBitmap 

Any content rendered by using the Render method of 
RenderTargetBitmap. 

Tiled content that uses TileBrush 

Any tiled content in which the TileMode property of the 
TileBrush is set to Tile. 

Surfaces that exceed the maximum texture size of the graphics 
hardware 

For most graphics hardware, large surfaces are 2048x2048 or 
4096x4096 pixels in size. 

Any operation whose video RAM requirement exceeds the 
memory of the graphics hardware 

You can monitor application video RAM usage by using the 
Perforator tool that is included in the WPF Performance Suite 

in the Windows SDK. 

Layered windows 

Layered windows allow WPF applications to render content to 
the screen in a non-rectangular window. On operating 
systems that support Windows Display Driver Model 
(WDDM), such as Windows Vista and Windows 7, layered 
windows are hardware accelerated. On other systems, such as 
Windows XP layered windows are rendered by software with 
no hardware acceleration. 

You can enable layered windows in WPF by setting the 
following Window properties: 

- WindowStyle = None 

- AllowsTransparency = true 

- Background = Transparent 

Other Resources 



The following resources can help you analyze the performance characteristics of your WPF application 

Graphics Rendering Registry Settings 

WPF provides four registry settings for controlling WPF rendering: 


SETTING 

DESCRIPTION 

Disable Hardware Acceleration Option 

Specifies whether hardware acceleration should be enabled. 

Maximum Multisample Value 

Specifies the degree of multisampling for antialiasing 3D 
content. 



SETTING 


DESCRIPTION 


Required Video Driver Date Setting Specifies whether the system disables hardware acceleration 

for drivers released before November 2004. 

Use Reference Rasterizer Option Specifies whether WPF should use the reference rasterizer. 

These settings can be accessed by any external configuration utility that knows how to reference the WPF registry 
settings. These settings can also be created or modified by accessing the values directly by using the Windows 
Registry Editor. For more information, see Graphics Rendering Registry Settings. 

WPF Performance Profiling Tools 

WPF provides a suite of performance profiling tools that allow you to analyze the run-time behavior of your 
application and determine the types of performance optimizations you can apply. The following table lists the 
performance profiling tools that are included in the Windows SDK tool, WPF Performance Suite: 

TOOL DESCRIPTION 

Perforator Use for analyzing rendering behavior. 

Visual Profiler Use for profiling the use of WPF services, such as layout and 

event handling, by elements in the visual tree. 

The WPF Performance Suite provides a rich, graphical view of performance data. For more information about WPF 
performance tools, see WPF Performance Suite. 

DirectX Diagnostic Tool 

The DirectX Diagnostic Tool, Dxdiag.exe, is designed to help you troubleshoot DirectX-related issues. The default 
installation folder for the DirectX Diagnostic Tool is: 

~\Windows\Systeni32 

When you run the DirectX Diagnostic Tool, the main window contains a set of tabs that allow you to display and 
diagnose DirectX-related information. For example, the System tab provides system information about your 
computer and specifies the version of DirectX that is installed on your computer. 




DirectX Diagnostic Tool main window 

See also 

• RenderCapability 

• RenderOptions 

• Optimizing WPF Application Performance 

• WPF Performance Suite 

• Graphics Rendering Registry Settings 

• Animation Tips and Tricks 
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This section is intended as a reference for Windows Presentation Foundation (WPF) application developers who 
are looking for ways to improve the performance of their applications. If you are a developer who is new to the 
Microsoft .NET Framework and WPF, you should first familiarize yourself with both platforms. This section 
assumes working knowledge of both, and is written for programmers who already know enough to get their 
applications up and running. 


NOTE 

The performance data provided in this section are based on WPF applications running on a 2.8 GHz PC with 512 RAM and 
an ATI Radeon 9700 graphics card. 


In This Section 

Planning for Application Performance 

Taking Advantage of Hardware 

Layout and Design 

2D Graphics and Imaging 

Object Behavior 

Application Resources 

Text 

Data Binding 
Controls 

Other Performance Recommendations 
Application Startup Time 

See also 

• RenderOptions 

• RenderCapability 

• Graphics Rendering Tiers 

• WPF Graphics Rendering Overview 

• Layout 

• Trees in WPF 

• Drawing Objects Overview 

• Using DrawingVisual Objects 

• Dependency Properties Overview 

• Freezable Objects Overview 

• XAML Resources 





Documents in WPF 
Drawing Formatted Text 
Typography in WPF 
Data Binding Overview 
Navigation Overview 
Animation Tips and Tricks 

Walkthrough: Caching Application Data in a WPF Application 


Planning for Application Performance 
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The success of achieving your performance goals depends on how well you develop your performance strategy. 
Planning is the first stage in developing any product. This topic describes a few very simple rules for developing a 
good performance strategy. 

Think in Terms of Scenarios 

Scenarios can help you focus on the critical components of your application. Scenarios are generally derived from 
your customers, as well as competitive products. Always study your customers and find out what really makes 
them excited about your product, and your competitors' products. Your customers' feedback can help you to 
determine your application's primary scenario. For instance, if you are designing a component that will be used at 
startup, it is likely that the component will be called only once, when the application starts up. Startup time 
becomes your key scenario. Other examples of key scenarios could be the desired frame rate for animation 
sequences, or the maximum working set allowed for the application. 

Define Goals 

Goals help you to determine whether an application is performing faster or slower. You should define goals for all 
of your scenarios. All performance goals that you define should be based on your customers' expectations. It may 
be difficult to set performance goals early on in the application development cycle, when there are still many 
unresolved issues. However, it is better to set an initial goal and revise it later than not to have a goal at all. 

Understand Your Platform 

Always maintain the cycle of measuring, investigating, refining/correcting during your application development 
cycle. From the beginning to the end of the development cycle, you need to measure your application's 
performance in a reliable, stable environment. You should avoid variability caused by external factors. For 
example, when testing performance, you should disable anti-virus or any automatic update such as SMS, in order 
not to impact performance test results. Once you have measured your application's performance, you need to 
identify the changes that will result in the biggest improvements. Once you have modified your application, start 
the cycle again. 

Make Performance Tuning an Iterative Process 

You should know the relative cost of each feature you will use. For example, the use of reflection in Microsoft .NET 
Framework is generally performance intensive in terms of computing resources, so you would want to use it 
judiciously. This does not mean to avoid the use of reflection, only that you should be careful to balance the 
performance requirements of your application with the performance demands of the features you use. 

Build Towards Graphical Richness 

A key technique for creating a scalable approach towards achieving WPF application performance is to build 
towards graphical richness and complexity. Always start with using the least performance intensive resources to 
achieve your scenario goals. Once you achieve these goals, build towards graphic richness by using more 
performance intensive features, always keeping your scenario goals in mind. Remember, WPF is a very rich 
platform and provides very rich graphic features. Using performance intensive features without thinking can 
negatively impact your overall application performance. 




WPF controls are inherently extensible by allowing for wide-spread customization of their appearance, while not 
altering their control behavior. By taking advantage of styles, data templates, and control templates, you can create 
and incrementally evolve a customizable user interface (Ul) that adapts to your performance requirements. 
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The internal architecture of WPF has two rendering pipelines, hardware and software. This topic provides 
information about these rendering pipelines to help you make decisions about performance optimizations of your 
applications. 

Hardware Rendering Pipeline 

One of the most important factors in determining WPF performance is that it is render bound—the more pixels 
you have to render, the greater the performance cost. However, the more rendering that can be offloaded to the 
graphics processing unit (GPU), the more performance benefits you can gain. The WPF application hardware 
rendering pipeline takes full advantage of Microsoft DirectX features on hardware that supports a minimum of 
Microsoft DirectX version 7.0. Further optimizations can be gained by hardware that supports Microsoft DirectX 
version 7.0 and PixelShader 2.0+ features. 

Software Rendering Pipeline 

The WPF software rendering pipeline is entirely CPU bound. WPF takes advantage of the SSE and SSE2 instruction 
sets in the CPU to implement an optimized, fully-featured software rasterizer. Fallback to software is seamless any 
time application functionality cannot be rendered using the hardware rendering pipeline. 

The biggest performance issue you will encounter when rendering in software mode is related to fill rate, which is 
defined as the number of pixels that you are rendering. If you are concerned about performance in software 
rendering mode, try to minimize the number of times a pixel is redrawn. For example, if you have an application 
with a blue background, which then renders a slightly transparent image over it, you will render all of the pixels in 
the application twice. As a result, it will take twice as long to render the application with the image than if you had 
only the blue background. 

Graphics Rendering Tiers 

It may be very difficult to predict the hardware configuration that your application will be running on. However, 
you might want to consider a design that allows your application to seamlessly switch features when running on 
different hardware, so that it can take full advantage of each different hardware configuration. 

To achieve this, WPF provides functionality to determine the graphics capability of a system at runtime. Graphics 
capability is determined by categorizing the video card as one of three rendering capability tiers. WPF exposes an 
API that allows an application to query the rendering capability tier. Your application can then take different code 
paths at run time depending on the rendering tier supported by the hardware. 

The features of the graphics hardware that most impact the rendering tier levels are: 

• Video RAM The amount of video memory on the graphics hardware determines the size and number of 
buffers that can be used for compositing graphics. 

• Pixel Shader A pixel shader is a graphics processing function that calculates effects on a per-pixel basis. 
Depending on the resolution of the displayed graphics, there could be several million pixels that need to be 
processed for each display frame. 

• Vertex Shader A vertex shader is a graphics processing function that performs mathematical operations 
on the vertex data of the object. 




• Multitexture Support Multitexture support refers to the ability to apply two or more distinct textures 
during a blending operation on a 3D graphics object. The degree of multitexture support is determined by 
the number of multitexture units on the graphics hardware. 

The pixel shader, vertex shader, and multitexture features are used to define specific DirectX version levels, which, 
in turn, are used to define the different rendering tiers in WPF. 

The features of the graphics hardware determine the rendering capability of a WPF application. The WPF system 
defines three rendering tiers: 

• Rendering Tier 0 No graphics hardware acceleration. The DirectX version level is less than version 7.0. 

• Rendering Tier 1 Partial graphics hardware acceleration. The DirectX version level is greater than or equal 
to version 7.0, and lesser than version 9.0. 

• Rendering Tier 2 Most graphics features use graphics hardware acceleration. The DirectX version level is 
greater than or equal to version 9.0. 

For more information on WPF rendering tiers, see Graphics Rendering Tiers. 
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The design of your WPF application can impact its performance by creating unnecessary overhead in calculating 
layout and validating object references. The construction of objects, particularly at run time, can affect the 
performance characteristics of your application. 

This topic provides performance recommendations in these areas. 

Layout 

The term "layout pass" describes the process of measuring and arranging the members of a Panel-derived 
object's collection of children, and then drawing them onscreen. The layout pass is a mathematically-intensive 
process—the larger the number of children in the collection, the greater the number of calculations required. For 
example, each time a child UlElement object in the collection changes its position, it has the potential to trigger a 
new pass by the layout system. Because of the close relationship between object characteristics and layout 
behavior, it's important to understand the type of events that can invoke the layout system. Your application will 
perform better by reducing as much as possible any unnecessary invocations of the layout pass. 

The layout system completes two passes for each child member in a collection: a measure pass, and an arrange 
pass. Each child object provides its own overridden implementation of the Measure and Arrange methods in 
order to provide its own specific layout behavior. At its simplest, layout is a recursive system that leads to an 
element being sized, positioned, and drawn onscreen. 

• A child UlElement object begins the layout process by first having its core properties measured. 

• The object's FrameworkElement properties that are related to size, such as Width, Height, and Margin, are 
evaluated. 

• Panel-specific logic is applied, such as the Dock property of the DockPanel, or the Orientation property of 
the StackPanel. 

• Content is arranged, or positioned, after all child objects have been measured. 

• The collection of child objects is drawn to the screen. 

The layout pass process is invoked again if any of the following actions occur: 

• A child object is added to the collection. 

• A LayoutTransform is applied to the child object. 

• The UpdateLayout method is called for the child object. 

• When a change occurs to the value of a dependency property that is marked with metadata affecting the 
measure or arrange passes. 

Use the Most Efficient Panel where Possible 

The complexity of the layout process is directly based on the layout behavior of the Panel-derived elements you 
use. For example, a Grid or StackPanel control provides much more functionality than a Canvas control. The price 
for this greater increase in functionality is a greater increase in performance costs. However, if you do not require 
the functionality that a Grid control provides, you should use the less costly alternatives, such as a Canvas or a 
custom panel. 




For more information, see Panels Overview. 


Update Rather than Replace a RenderTransform 

You may be able to update a Transform rather than replacing it as the value of a RenderTransform property. This 
is particularly true in scenarios that involve animation. By updating an existing Transform, you avoid initiating an 
unnecessary layout calculation. 

Build Your Tree Top-Down 

When a node is added or removed from the logical tree, property invalidations are raised on the node's parent 
and all its children. As a result, a top-down construction pattern should always be followed to avoid the cost of 
unnecessary invalidations on nodes that have already been validated. The following table shows the difference in 
execution speed between building a tree top-down versus bottom-up, where the tree is 150 levels deep with a 
single TextBlock and DockPanel at each level. 


RENDER—INCLUDES TREE BUILDING 

ACTION TREE BUILDING (IN MS) (IN MS) 

Bottom-up 366 454 

Top-down 11 96 


The following code example demonstrates how to create a tree top down. 

private void OnBuildTreeTopDown(object senderj RoutedEventArgs e) 

{ 

TextBlock textBlock = new TextBlock()j 
textBlock.Text = "Default"; 

DockPanel parentPanel = new DockPanel(); 

DockPanel childPanel; 

myCanvas.Children.Add(parentPanel); 
myCanvas.Children.Add(textBlock); 

for (int i = 0; i < 150; i++) 

{ 

textBlock = new TextBlock(); 
textBlock.Text = "Default"; 
parentPanel.Children.Add(textBlock); 

childPanel = new DockPanel(); 

parentPanel.Children.Add(childPanel); 

parentPanel = childPanel; 

} 

} 



Private Sub OnBuildTreeTopDown(By\/al sender As Object^ ByVal e As RoutedEventArgs) 
Dim textBlock As New TextBlock() 
textBlock.Text = "Default" 

Dim parentPanel As New DockPanel() 

Dim childPanel As DockPanel 

myCanvas.Children.Add(parentPanel) 
myCanvas.Children.Add(textBlock) 

For i As Integer = 0 To 149 

textBlock = New TextBlock() 

textBlock.Text = "Default" 

parentPanel.Children.Add(textBlock) 

childPanel = New DockPanel() 
parentPanel.Children.Add(childPanel) 
parentPanel = childPanel 
Next i 
End Sub 


For more information on the logical tree, see Trees in WPF. 
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WPF provides a wide range of 2D graphics and imaging functionality that can be optimized for your application 
requirements. This topic provides information about performance optimization in those areas. 

Drawing and Shapes 

WPF provides both Drawing and Shape objects to represent graphical drawing content. However, Drawing objects 
are simpler constructs than Shape objects and provide better performance characteristics. 

A Shape allows you to draw a graphical shape to the screen. Because they are derived from the 
FrameworkElement class, Shape objects can be used inside panels and most controls. 

WPF offers several layers of access to graphics and rendering services. At the top layer, Shape objects are easy to 
use and provide many useful features, such as layout and event handling. WPF provides a number of ready-to- 
use shape objects. All shape objects inherit from the Shape class. Available shape objects include Ellipse, Line, 

Path, Polygon, Polyline, and Rectangle. 

Drawing objects, on the other hand, do not derive from the FrameworkElement class and provide a lighter-weight 
implementation for rendering shapes, images, and text. 

There are four types of Drawing objects: 

• GeometryDrawing Draws a shape. 

• ImageDrawing Draws an image. 

• GlyphRunDrawing Draws text. 

• DrawingGroup Draws other drawings. Use a drawing group to combine other drawings into a single 
composite drawing. 

The GeometryDrawing object is used to render geometry content. The Geometry class and the concrete classes 
that derive from it, such as CombinedGeometry, EllipseGeometry, and PathGeometry, provide a means for 
rendering 2D graphics and providing hit-testing and clipping support. Geometry objects can be used to define the 
region of a control, for example, or to define the clip region to apply to an image. Geometry objects can be simple 
regions, such as rectangles and circles, or composite regions created from two or more geometry objects. More 
complex geometric regions can be created by combining PathSegment-derived objects, such as ArcSegment, 
BezierSegment, and QuadraticBezierSegment. 

On the surface, the Geometry class and the Shape class are similar. Both are used in the rendering of 2D graphics 
and both have similar concrete classes that derive from them, for example, EllipseGeometry and Ellipse. However, 
there are important differences between these two sets of classes. For one, the Geometry class lacks some of the 
functionality of the Shape class, such as the ability to draw itself To draw a geometry object, another class such as 
DrawingContext, Drawing, or a Path (it is worth noting that a Path is a Shape) must be used to perform the 
drawing operation. Rendering properties such as fill, stroke, and the stroke thickness are on the class that draws 
the geometry object, while a shape object contains these properties. One way to think of this difference is that a 
geometry object defines a region, for example, a circle, while a shape object defines a region, defines how that 
region is filled and outlined, and participates in the layout system. 

Since Shape objects derive from the FrameworkElement class, using them can add significantly more memory 
consumption in your application. If you really do not need the FrameworkElement features for your graphical 




content, consider using the lighter-weight Drawing objects. 

For more information on Drawing objects, see Drawing Objects Overview. 

StreamGeometry Objects 

The StreamGeometry object is a lightweight alternative to PathGeometry for creating geometric shapes. Use a 
StreamGeometry when you need to describe a complex geometry. StreamGeometry is optimized for handling 
many PathGeometry objects and performs better when compared to using many individual PathGeometry 
objects. 

The following example uses attribute syntax to create a triangular StreamGeometry in XAML. 

<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"> 

<StackPanel> 

<Path Data="F0 M10,100 L100,100 100,502" 

Str'okeThicl<ness="l" Str'oke="Black"/> 

</StackPanel> 

</Page> 

For more information on StreamGeometry objects, see Create a Shape Using a StreamGeometry. 

DrawingVisual Objects 

The DrawingVisual object is a lightweight drawing class that is used to render shapes, images, or text. This class is 
considered lightweight because it does not provide layout or event handling, which improves its performance. For 
this reason, drawings are ideal for backgrounds and clip art. For more information, see Using DrawingVisual 
Objects. 

Images 

WPF imaging provides a significant improvement over the imaging capabilities in previous versions of Windows. 
Imaging capabilities, such as displaying a bitmap or using an image on a common control, were primarily 
handled by the Microsoft Windows Graphics Device Interface (GDI) or Microsoft Windows GDI+ application 
programming interface (API). These APIs provided baseline imaging functionality but lacked features such as 
support for codec extensibility and high fidelity image support. WPF Imaging APIs have been redesigned to 
overcome the shortcomings of GDI and GDI+ and provide a new set of APIs to display and use images within 
your applications. 

When using images, consider the following recommendations for gaining better performance: 

• If your application requires you to display thumbnail images, consider creating a reduced-sized version of 
the image. By default, WPF loads your image and decodes it to its full size. If you only want a thumbnail 
version of the image, WPF unnecessary decodes the image to its full-size and then scales it down to a 
thumbnail size. To avoid this unnecessary overhead, you can either request WPF to decode the image to a 
thumbnail size, or request WPF to load a thumbnail size image. 

• Always decode the image to desired size and not to the default size. As mentioned above, request WPF to 
decode your image to a desired size and not the default full size. You will reduce not only your application's 
working set, but execution speed as well. 

• If possible, combine the images into a single image, such as a film strip composed of multiple images. 

• For more information, see Imaging Overview. 



B itmapScaling Mode 

When aninnating the scale of any bitmap, the default high-quality image resampling algorithm can sometimes 
consume sufficient system resources to cause frame rate degradation, effectively causing animations to stutter. By 
setting the BitmapScalingMode property of the RenderOptions object to LowQuality, you can create a smoother 
animation when scaling a bitmap. LowQuality mode tells the WPF rendering engine to switch from a quality- 
optimized algorithm to a speed-optimized algorithm when processing images. 

The following example shows how to set the BitmapScalingMode for an image object. 

// Set the bitmap scaling mode for the image to render faster. 

RenderOptions.SetBitmapScalingMode(MyImage, BitmapScalingMode.LowQuality); 

' Set the bitmap scaling mode for the image to render faster. 

RenderOptions.SetBitmapScalingMode(MyImage, BitmapScalingMode.LowQuality) 


Caching Hint 

By default, WPF does not cache the rendered contents of TileBrush objects, such as DrawingBrush and 
VisualBrush. In static scenarios where the contents or use of the TileBrush in the scene aren't changing, this makes 
sense, since it conserves video memory. It does not make as much sense when a TileBrush with static content is 
used in a non-static way—for example, when a static DrawingBrush or VisualBrush is mapped to the surface of a 
rotating 3D object. The default behavior of WPF is to re-render the entire content of the DrawingBrush or 
VisualBrush for every frame, even though the content is unchanging. 

By setting the CachingHint property of the RenderOptions object to Cache, you can increase performance by 
using cached versions of the tiled brush objects. 

The CacheInvalidationThresholdMinimum and CacheInvalidationThresholdMaximum property values are relative 
size values that determine when the TileBrush object should be regenerated due to changes in scale. For example, 
by setting the CacheInvalidationThresholdMaximum property to 2.0, the cache for the TileBrush only needs to be 
regenerated when its size exceeds twice the size of the current cache. 

The following example shows how to use the caching hint option for a DrawingBrush. 

DrawingBrush drawingBrush = new DrawingBrush(); 

// Set the caching hint option for the brush. 

RenderOptions.SetCachingHint(drawingBrush, CachingHint.Cache); 

// Set the minimum and maximum relative sizes for regenerating the tiled brush. 

// The tiled brush will be regenerated and re-cached when its size is 
// 0.5x or 2x of the current cached size. 

RenderOptions.SetCacheInvalidationThresholdMinimum(drawingBrush, 0.5); 

RenderOptions.SetCacheInvalidationThresholdMaximum(drawingBrush, 2.0); 


Dim drawingBrush As New DrawingBrushQ 

' Set the caching hint option for the brush. 

RenderOptions.SetCachingHint(drawingBrush, CachingHint.Cache) 

' Set the minimum and maximum relative sizes for regenerating the tiled brush. 
' The tiled brush will be regenerated and re-cached when its size is 
' 0.5x or 2x of the current cached size. 

RenderOptions.SetCacheInvalidationThresholdMinimum(drawingBrush, 0.5) 

RenderOptions.SetCacheInvalidationThresholdMaximum(drawingBrush, 2.0) 
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Understanding the intrinsic behavior of WPF objects will help you make the right tradeoffs between functionality 
and performance. 

Not Removing Event Handlers on Objects may Keep Objects Alive 

The delegate that an object passes to its event is effectively a reference to that object. Therefore, event handlers 
can keep objects alive longer than expected. When performing clean up of an object that has registered to listen 
to an object's event, it is essential to remove that delegate before releasing the object. Keeping unneeded objects 
alive increases the application's memory usage. This is especially true when the object is the root of a logical tree 
or a visual tree. 

WPF introduces a weak event listener pattern for events that can be useful in situations where the object lifetime 
relationships between source and listener are difficult to keep track of Some existing WPF events use this pattern. 
If you are implementing objects with custom events, this pattern may be of use to you. For details, see Weak 
Event Patterns. 

There are several tools, such as the CLR Profiler and the Working Set Viewer, that can provides information on the 
memory usage of a specified process. The CLR Profiler includes a number of very useful views of the allocation 
profile, including a histogram of allocated types, allocation and call graphs, a time line showing garbage 
collections of various generations and the resulting state of the managed heap after those collections, and a call 
tree showing per-method allocations and assembly loads. For more information, see Performance. 

Dependency Properties and Objects 

In general, accessing a dependency property of a DependencyObject is not slower than accessing a CLR property. 
While there is a small performance overhead for setting a property value, getting a value is as fast as getting the 
value from a CLR property. Offsetting the small performance overhead is the fact that dependency properties 
support robust features, such as data binding, animation, inheritance, and styling. For more information, see 
Dependency Properties Overview. 

DependencyProperty Optimizations 

You should define dependency properties in your application very carefully. If your DependencyProperty affects 
only render type metadata options, rather than other metadata options such as Affects Measure, you should mark 
it as such by overriding its metadata. For more information about overriding or obtaining property metadata, see 
Dependency Property Metadata. 

It may be more efficient to have a property change handler invalidate the measure, arrange, and render passes 
manually if not all property changes actually affect measure, arrange, and render. For instance, you might decide 
to re-render a background only when a value is greater than a set limit. In this case, your property change 
handler would only invalidate render when the value exceeds the set limit. 

Making a DependencyProperty Inheritable is Not Free 

By default, registered dependency properties are non-inheritable. However, you can explicitly make any property 
inheritable. While this is a useful feature, converting a property to be inheritable impacts performance by 
increasing the length of time for property invalidation. 

Use RegisterClassHandler Carefully 

While calling RegisterClassHandler allows you to save your instance state, it is important to be aware that the 




handler is called on every instance, which can cause performance problems. Only use RegisterClassHandler when 
your application requires that you save your instance state. 

Set the Default Value for a DependencyProperty during Registration 

When creating a DependencyProperty that requires a default value, set the value using the default metadata 
passed as a parameter to the Register method of the DependencyProperty. Use this technique rather than setting 
the property value in a constructor or on each instance of an element. 

Set the PropertyMetadata Value using Register 

When creating a DependencyProperty, you have the option of setting the PropertyMetadata using either the 
Register or OverrideMetadata methods. Although your object could have a static constructor to call 
OverrideMetadata, this is not the optimal solution and will impact performance. For best performance, set the 
PropertyMetadata during the call to Register. 

Freezable Objects 

A Freezable is a special type of object that has two states: unfrozen and frozen. Freezing objects whenever 
possible improves the performance of your application and reduces its working set. For more information, see 
Freezable Objects Overview. 

Each Freezable has a Changed event that is raised whenever it changes. However, change notifications are costly 
in terms of application performance. 

Consider the following example in which each Rectangle uses the same Brush object: 

rectangle_l.Fill = myBrush; 
rectangle_2.Fill = myBrush; 
rectangle_3.Fill = myBrush; 

H ... 

rectangle_10.Fill = myBnush; 

rectangle_l.Fill = myBrush 
rectangle_2.Fill = myBrush 
rectangle_3.Fill = myBrush 

rectangle_10.Fill = myBrush 

By default, WPF provides an event handler for the SolidColorBrush object's Changed event in order to invalidate 
the Rectangle object's Fill property. In this case, each time the SolidColorBrush has to fire its Changed event it is 
required to invoke the callback function for each Rectangle— the accumulation of these callback function 
invocations impose a significant performance penalty. In addition, it is very performance intensive to add and 
remove handlers at this point since the application would have to traverse the entire list to do so. If your 
application scenario never changes the SolidColorBrush, you will be paying the cost of maintaining Changed 
event handlers unnecessarily. 

Freezing a Freezable can improve its performance, because it no longer needs to expend resources on 
maintaining change notifications. The table below shows the size of a simple SolidColorBrush when its IsFrozen 
property is set to true , compared to when it is not. This assumes applying one brush to the Fill property of ten 
Rectangle objects. 

STATE SIZE 

212 Bytes 


Frozen SolidColorBrush 




STATE 


SIZE 


Non-frozen SolidColorBrush 972 Bytes 

The following code sample demonstrates this concept: 

Brush frozenBrush = new SolidColorBrush(Colons.Blue); 
frozenBrush.Freeze(); 

Brush nonFrozenBrush = new SolidColorBrush(Colors.Blue); 

for (int i = 0; i < 10; i++) 

{ 

// Create a Rectangle using a non-frozed Brush. 

Rectangle rectangleNonFrozen = new Rectangle(); 
rectangleNonFrozen.Fill = nonFrozenBrush; 

// Create a Rectangle using a frozed Brush. 

Rectangle rectangleFrozen = new Rectangle(); 
rectangleFrozen.Fill = frozenBrush; 

} 


Dim frozenBrush As Brush = New SolidColorBrush(Colors.Blue) 
frozenBrush.Freeze() 

Dim nonFrozenBrush As Brush = New SolidColorBrush(Colors.Blue) 

For i As Integer = 0 To 9 

' Create a Rectangle using a non-frozed Brush. 

Dim rectangleNonFrozen As New Rectangle() 
rectangleNonFrozen.Fill = nonFrozenBrush 

' Create a Rectangle using a frozed Brush. 

Dim rectangleFrozen As New Rectangle() 
rectangleFrozen.Fill = frozenBrush 
Next i 


Changed Handlers on Unfrozen Freezables may Keep Objects Alive 

The delegate that an object passes to a Freezable object's Changed event is effectively a reference to that object. 
Therefore, Changed event handlers can keep objects alive longer than expected. When performing clean up of an 
object that has registered to listen to a Freezable object's Changed event, it is essential to remove that delegate 
before releasing the object. 

WPF also hooks up Changed events internally. For example, all dependency properties which take Freezable as a 
value will listen to Changed events automatically. The Fill property, which takes a Brush, illustrates this concept. 

Brush myBrush = new SolidColorBrush(Colors.Red); 

Rectangle myRectangle = new Rectangle(); 
myRectangle.Fill = myBrush; 


Dim myBrush As Brush = New SolidColorBrush(Colors.Red) 

Dim myRectangle As New Rectangle() 
myRectangle.Fill = myBrush 

On the assignment of myBrush to myRectangle.Fill , a delegate pointing back to the Rectangle object will be 
added to the SolidColorBrush object's Changed event. This means the following code does not actually make 
myRect eligible for garbage collection: 







myRectangle = null; 


myRectangle = Nothing 

In this case mysnush is Still keeping myRectangle alive and will call back to it when it fires its Changed event. Note 
that assigning myBrush to the Fill property of a new Rectangle will simply add another event handler to myBrush . 

The recommended way to clean up these types of objects is to remove the Brush from the Fill property, which will 
in turn remove the Changed event handler. 

myRectangle.Fill = null; 
myRectangle = null; 


myRectangle.Fill = Nothing 
myRectangle = Nothing 


User Interface Virtualization 

WPF also provides a variation of the StackPanel element that automatically "virtualizes" data-bound child content. 
In this context, the word virtualize refers to a technique by which a subset of objects are generated from a larger 
number of data items based upon which items are visible on-screen. It is intensive, both in terms of memory and 
processor, to generate a large number of Ul elements when only a few may be on the screen at a given time. 
VirtualizingStackPanel (through functionality provided by VirtualizingPanel) calculates visible items and works 
with the ItemContainerGenerator from an ItemsControl (such as ListBox or ListView) to only create elements for 
visible items. 

As a performance optimization, visual objects for these items are only generated or kept alive if they are visible 
on the screen. When they are no longer in the viewable area of the control, the visual objects may be removed. 
This is not to be confused with data virtualization, where data objects are not all present in the local collection- 
rather streamed in as needed. 

The table below shows the elapsed time adding and rendering 5000 TextBlock elements to a StackPanel and a 
VirtualizingStackPanel. In this scenario, the measurements represent the time between attaching a text string to 
the ItemsSource property of an ItemsControl object to the time when the panel elements display the text string. 

HOST PANEL RENDER TIME (MS) 

StackPanel 3210 

VirtualizingStackPanel 46 
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WPF allows you to share application resources so that you can support a consistent look or behavior across 
similar-typed elements. This topic provides a few recommendations in this area that can help you improve the 
performance of your applications. 

For more information on resources, see XAML Resources. 

Sharing resources 

If your application uses custom controls and defines resources in a ResourceDictionary (or XAML Resources 
node), it is recommended that you either define the resources at the Application or Window object level, or 
define them in the default theme for the custom controls. Defining resources in a custom control's 
ResourceDictionary imposes a performance impact for every instance of that control. For example, if you have 
performance-intensive brush operations defined as part of the resource definition of a custom control and many 
instances of the custom control, the application's working set will increase significantly. 

To illustrate this point, consider the following. Let's say you are developing a card game using WPF. For most card 
games, you need 52 cards with 52 different faces. You decide to implement a card custom control and you define 
52 brushes (each representing a card face) in the resources of your card custom control. In your main application, 
you initially create 52 instances of this card custom control. Each instance of the card custom control generates 
52 instances of Brush objects, which gives you a total of 52 * 52 Brush objects in your application. By moving the 
brushes out of the card custom control resources to the Application or Window object level, or defining them in 
the default theme for the custom control, you reduce the working set of the application, since you are now 
sharing the 52 brushes among 52 instances of the card control. 

Sharing a Brush without Copying 

If you have multiple elements using the same Brush object, define the brush as a resource and reference it, rather 
than defining the brush inline in XAML. This method will create one instance and reuse it, whereas defining 
brushes inline in XAML creates a new instance for each element. 

The following markup sample illustrates this point: 




<StackPanel.Resources) 

<LinearGradientBrush x:Key="myBrush" StartPoint="0,0.5" EndPoint="lj0.5" Opacity="0.5"> 
<LinearGradientBrush.GradientStops) 

<GradientStopCollection> 

<GradientStop Color="GoldenRod" Offset="0" /> 

<GradientStop Color="White" Offset="l" /> 

</GradlentStopCollection> 

</LinearGradientBrush.GradientStops) 

</LinearGradientBrush> 

</StackPanel.Resources) 

<!-- Non-shared Brush object. --) 

<Label) 

Label 1 

<Label.Background) 

<LinearGradientBrush StartPoint="0j0.5" EndPoint="lj0.5" Opacity="0.5") 

<LinearGradientBrush.GradientStops) 

<GradientStopCollection) 

cGradientStop Color="GoldenRod" Offset="0" /) 

<GradientStop Color="White" Offset="l" /) 

</GradientStopCollection) 

</LinearGradientBrush.GradientStops) 

</LinearGradientBrush) 

</Label.Background) 

</Label) 

<!-- Shared Brush object. --) 

<Label Background="{StaticResource myBrush}")Label 2</Label) 

<Label Background="{StaticResource myBrush}")Label 3</Label) 


Use Static Resources when Possible 

A Static resource provides a value for any XAML property attribute by looking up a reference to an already 
defined resource. Lookup behavior for that resource is analogous to compile-time lookup. 

A dynamic resource, on the other hand, will create a temporary expression during the initial compilation and thus 
defer lookup for resources until the requested resource value is actually required in order to construct an object. 
Lookup behavior for that resource is analogous to run-time lookup, which imposes a performance impact. Use 
Static resources whenever possible in your application, using dynamic resources only when necessary. 

The following markup sample shows the use of both types of resources: 

<StackPanel.Resources) 

<SolidColorBrush x:Key="myBrush" Color="Teal"/) 

</StackPanel.Resources) 

<!-- StaticResource reference --) 

<Label Foreground="{StatlcResource myBrush}")Label 1</Label) 

<!-- DynamicResource reference --) 

<Label Foreground="{DynamicResource {x:Static SystemColors.ControlBrushKey}}")Label 2</Label) 


See also 

• Optimizing WPF Application Performance 

• Planning for Application Performance 

• Taking Advantage of Hardware 

• Layout and Design 

• 2D Graphics and Imaging 
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WPF includes support for the presentation of text content through the use of feature-rich user interface (Ul) 
controls. In general you can divide text rendering in three layers: 

1. Using the Glyphs and GlyphRun objects directly. 

2. Using the FormattedText object. 

3. Using high-level controls, such as the TextBlock and FlowDocument objects. 

This topic provides text rendering performance recommendations. 

Rendering Text at the Glyph Level 

Windows Presentation Foundation (WPF) provides advanced text support including glyph-level markup with 
direct access to Glyphs for customers who want to intercept and persist text after formatting. These features 
provide critical support for the different text rendering requirements in each of the following scenarios. 

• Screen display of fixed-format documents. 

• Print scenarios. 

o Extensible Application Markup Language (XAML) as a device printer language, 
o Microsoft XPS Document Writer. 

o Previous printer drivers, output from Win32 applications to the fixed format, 
o Print spool format. 

• Fixed-format document representation, including clients for previous versions of Windows and other 
computing devices. 

NOTE 

Glyphs and GlyphRun are designed for fixed-format document presentation and print scenarios. Windows Presentation 
Foundation (WPF) provides several elements for general layout and user interface (Ul) scenarios such as Label and 
TextBlock. For more information on layout and Ul scenarios, see the Typography in WPF. 


The following examples show how to define properties for a Glyphs object in Extensible Application Markup 
Language (XAML). The Glyphs object represents the output of a GlyphRun in XAML. The examples assume that 
the Arial, Courier New, and Times New Roman fonts are installed in the C:\WINDOWS\Fonts folder on the 
local computer. 





<!-- The example shows how to use a Glyphs object. --> 
<Page 


xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 


> 


<StackPanel Bacl<gr'ound="Powder'Blue"> 


<Glyphs 

FontUri 


= "C:\WINDOWS\Fonts\TIMES.TTF" 


FontRendeningEmSize = "100" 


StyleSimulations 

UnicodeString 

Fill 

OniginX 

OniginY 


"BoldSimulation" 
"Flello World!" 
"Black" 

" 100 " 

" 200 " 


/> 

</StackPanel> 

</Page> 

Using DrawGIyphRun 

If you have custom control and you want to render glyphs, use the DrawGIyphRun method. 

WPF also provides lower-level services for custom text formatting through the use of the FormattedText object. 
The most efficient way of rendering text in Windows Presentation Foundation (WPF) is by generating text 
content at the glyph level using Glyphs and GlyphRun. However, the cost of this efficiency is the loss of easy to 
use rich text formatting, which are built-in features of Windows Presentation Foundation (WPF) controls, such as 
TextBlock and FlowDocument. 


FormattedText Object 


The FormattedText object allows you to draw multi-line text, in which each character in the text can be 
individually formatted. For more information, see Drawing Formatted Text. 

To create formatted text, call the FormattedText constructor to create a FormattedText object. Once you have 
created the initial formatted text string, you can apply a range of formatting styles. If your application wants to 
implement its own layout, then the FormattedText object is better choice than using a control, such as TextBlock. 
For more information on the FormattedText object, see Drawing Formatted Text . 

The FormattedText object provides low-level text formatting capability. You can apply multiple formatting styles 
to one or more characters. For example, you could call both the SetFontSize and SetForegroundBrush methods 
to change the formatting of the first five characters in the text. 


The following code example creates a FormattedText object and renders it. 



protected override void OnRender(DrawingContext drawingContext) 

{ 

string teststring = "Lorem ipsum dolor sit ametj consectetur adipisicing elitj sed do eiusmod tempor"; 

// Create the initial formatted text string. 

FormattedText formattedText = new FormattedText( 
testStringj 

CultureInfo.GetCultureInfo("en-us")j 
FlowDirection.LeftToRightj 
new Typeface("Verdana" 

32, 

Brushes.Black); 

// Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears. 
formattedText.MaxTextWidth = 300; 
formattedText.MaxTextHeight = 240; 

// Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters. 
// The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSlze(36 * (96.0 / 72.0), 0, 5); 

// Use a Bold font weight beginning at the 6th character and continuing for 11 characters. 
formattedText.SetFontWeight(FontWeights.Bold, 6, 11); 

// Use a linear gradient brush beginning at the 6th character and continuing for 11 characters. 
formattedText.SetForegroundBrush( 

new LinearGradientBrush( 

Colors.Orange, 

Colors.Teal, 

90.0), 

6 , 11 ); 

// Use an Italic font style beginning at the 28th character and continuing for 28 characters. 
formattedText.SetFontStyle(FontStyles.Italic, 28, 28); 

// Draw the formatted text string to the DrawingContext of the control. 
drawingContext.DrawText(formattedText, new Point(10, 0)); 



Protected Overrides Sub OnRender(By\/al drawingContext As DrawingContext) 

Dim teststring As String = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor" 

' Create the initial formatted text string. 

Dim formattedText As New FormattedText(testStringj CultureInfo.GetCultureInfo("en-us"), 
FlowDirection.LeftToRight^ New Typeface("Verdana")j 32, Brushes.Black) 

' Set a maximum width and height. If the text overflows these values, an ellipsis "..." appears. 
formattedText.MaxTextWidth = 300 
formattedText.MaxTextHeight = 240 

' Use a larger font size beginning at the first (zero-based) character and continuing for 5 characters. 
' The font size is calculated in terms of points -- not as device-independent pixels. 
formattedText.SetFontSlze(36 * (96.0 / 72.0), 0, 5) 

' Use a Bold font weight beginning at the 6th character and continuing for 11 characters. 
formattedText.SetFontWeight(FontWeights.Bold, 6, 11) 

' Use a linear gradient brush beginning at the 6th character and continuing for 11 characters. 
formattedText.SetForegroundBrush(New LinearGradientBrush(Colors.Orange, Colors.Teal, 90.0), 6, 11) 

' Use an Italic font style beginning at the 28th character and continuing for 28 characters. 
formattedText.SetFontStyle(FontStyles.Italic, 28, 28) 

' Draw the formatted text string to the DrawingContext of the control. 
drawingContext.DrawText(formattedText, New Point(10, 0)) 

End Sub 


FlowDocumerit, TextBlock, and Label Controls 

WPF includes multiple controls for drawing text to the screen. Each control is targeted to a different scenario and 
has its own list of features and limitations. 

FlowDocument Impacts Performance More than TextBlock or Label 

In general, the TextBlock element should be used when limited text support is required, such as a brief sentence 
in a user interface (Ul). Label can be used when minimal text support is required. The FlowDocument element is 
a container for re-flowable documents that support rich presentation of content, and therefore, has a greater 
performance impact than using the TextBlock or Label controls. 

For more information on FlowDocument, see Flow Document Overview. 

Avoid Using TextBlock in FlowDocument 

The TextBlock element is derived from UlElement. The Run element is derived from TextElement, which is less 
costly to use than a UlElement-derived object. When possible, use Run rather than TextBlock for displaying text 
content in a FlowDocument. 

The following markup sample illustrates two ways of setting text content within a FlowDocument: 



<FlowDocument> 

<!-- Text content within a Run (more efficient). --> 
<Paragnaph> 

<Run>Line one</Run> 

</Paragraph> 

<!-- Text content within a TextBlock (less efficient). --> 
<Paragnaph> 

<TextBlock>Line two</TextBlock> 

</Panagraph> 

</FlowDocument> 


Avoid Using Run to Set Text Properties 

In general, using a Run within a TextBlock is more performance intensive than not using an explicit Run object at 
all. If you are using a Run in order to set text properties, set those properties directly on the TextBlock instead. 

The following markup sample illustrates these two ways of setting a text property, in this case, the FontWeight 
property: 

<!-- Run is used to set text properties. --> 

<TextBlock> 

<Run FontWeight="Bold">HellOj world</Run> 

</TextBlock> 

<!-- TextBlock is used to set text properties^ which is more efficient. --> 

<TextBlock FontWeight="Bold"> 

Flello, world 
</TextBlock> 


The following table shows the cost of displaying 1000 TextBlock objects with and without an explicit Run. 

TEXTBLOCK TYPE CREATION TIME (MS) RENDER TIME (MS) 

Run setting text properties 146 540 

TextBlock setting text properties 43 453 


Avoid Databinding to the Label.Content Property 

Imagine a scenario where you have a Label object that is updated frequently from a String source. When data 
binding the Label element's Content property to the String source object, you may experience poor 
performance. Each time the source String is updated, the old String object is discarded and a new String is 
recreated—because a String object is immutable, it cannot be modified. This, in turn, causes the 
ContentPresenter of the Label object to discard its old content and regenerate the new content to display the 
new String. 

The solution to this problem is simple. If the Label is not set to a custom ContentTemplate value, replace the 
Label with a TextBlock and data bind its Text property to the source string. 

DATA BOUND PROPERTY UPDATE TIM E (MS) 

Label.Content 835 


TextBlock.Text 


242 




Hyperlink 

The Hyperlink object is an inline-level flow content element that allows you to host hyperlinks within the flow 
content. 

Combine Hyperlinks in One TextBlock Object 

You can optimize the use of multiple Hyperlink elements by grouping them together within the same TextBlock. 
This helps to minimize the number of objects you create in your application. For example, you may want to 
display multiple hyperlinks, such as the following: 

MSN Home | My MSN 

The following markup example shows multiple TextBlock elements used to display the hyperlinks: 

<!-- Hyperlinks in separate TextBlocks. --> 

<TextBlock> 

<Hyperlink TextDecorations="None" NavigateLlri="http://www.msn.com">MSN Home</Hyperlink> 

</TextBlock> 

<TextBlock Text=" | "/> 

<TextBlock> 

<Hyperlink TextDecorations="None" IMavigateUri="http://my.msn.com">My MSN</Hyperlink> 

</TextBlock> 


The following markup example shows a more efficient way of displaying the hyperlinks, this time, using a single 
TextBlock: 


<!-- Hyperlinks combined in the same TextBlock. --> 

<TextBlock> 

<Hyperlink TextDecorations="None" IMavigateUri="http://www.msn.com">MSN Home</Hyperlink> 
<Run Text=" | " /> 

<Hyperlink TextDecorations="None" IMavigateUri="http://my.msn.com">My MSN</Hyperlink> 
</TextBlock> 


Showing Underlines on Hyperlinks Only on MouseEnter Events 

A TextDecoration object is a visual ornamentation that you can add to text; however, it can be performance 
intensive to instantiate. If you make extensive use of Hyperlink elements, consider showing an underline only 
when triggering an event, such as the MouseEnter event. For more information, see Specify Whether a Hyperlink 
is Underlined. 

The following image shows how the MouseEnter event triggers the underlined hyperlink: 




MSN Home | My MSN 



The following markup sample shows a Hyperlink defined with and without an underline: 

















<!-- Hyperlink with default underline. --> 

<Hyperlink NavigateUri="http://www.msn.com"> 

MSN Home 
</Hyperlink> 

<Run Text=" | " /> 

<!-- Hyperlink with no underline. --> 

<Hyperlink Name="myHyperlink" TextDecorations="None" 
MouseEnter="OnMouseEnter" 
MouseLeave="OnMouseLeave" 
NavigateLlri="http: //www. msn. com" > 

My MSN 
</Hyperlink> 


The following table shows the performance cost of displaying 1000 Hyperlink elements with and without an 
underline. 

HYPERLINK CREATION TIME (MS) RENDER TIME (MS) 

With underline 289 1130 

Without underline 299 776 


Text Formatting Features 

WPF provides rich text formatting services, such as automatic hyphenations. These services may impact 
application performance and should only be used when needed. 

Avoid Unnecessary Use of Hyphenation 

Automatic hyphenation finds hyphen breakpoints for lines of text, and allows additional break positions for lines 
in TextBlock and FlowDocument objects. By default, the automatic hyphenation feature is disabled in these 
objects. You can enable this feature by setting the object's IsHyphenationEnabled property to true . However, 
enabling this feature causes WPF to initiate Component Object Model (COM) interoperability, which can impact 
application performance. It is recommended that you do not use automatic hyphenation unless you need it. 

Use Figures Carefully 

A Figure element represents a portion of flow content that can be absolutely-positioned within a page of 
content. In some cases, a Figure may cause an entire page to automatically reformat if its position collides with 
content that has already been laid-out. You can minimize the possibility of unnecessary reformatting by either 
grouping Figure elements next to each other, or declaring them near the top of content in a fixed page size 
scenario. 

Optimal Paragraph 

The optimal paragraph feature of the FlowDocument object lays out paragraphs so that white space is 
distributed as evenly as possible. By default, the optimal paragraph feature is disabled. You can enable this 
feature by setting the object's IsOptimalParagraphEnabled property to true . However, enabling this feature 
impacts application performance. It is recommended that you do not use the optimal paragraph feature unless 
you need it. 

See also 

• Optimizing WPF Application Performance 

• Planning for Application Performance 

• Taking Advantage of Hardware 
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Windows Presentation Foundation (WPF) data binding provides a simple and consistent way for applications to 
present and interact with data. Elements can be bound to data from a variety of data sources in the form of CLR 
objects and XML. 

This topic provides data binding performance recommendations. 

How Data Binding References are Resolved 

Before discussing data binding performance issues, it is worthwhile to explore how the Windows Presentation 
Foundation (WPF) data binding engine resolves object references for binding. 

The source of a Windows Presentation Foundation (WPF) data binding can be any CLR object. You can bind to 
properties, sub-properties, or indexers of a CLR object. The binding references are resolved by using either 
Microsoft .NET Framework reflection or an ICustomTypeDescriptor. Here are three methods for resolving object 
references for binding. 

The first method involves using reflection. In this case, the Propertyinfo object is used to discover the attributes 
of the property and provides access to property metadata. When using the ICustomTypeDescriptor interface, the 
data binding engine uses this interface to access the property values. The ICustomTypeDescriptor interface is 
especially useful in cases where the object does not have a static set of properties. 

Property change notifications can be provided either by implementing the INotifyPropertyChanged interface or 
by using the change notifications associated with the TypeDescriptor. However, the preferred strategy for 
implementing property change notifications is to use INotifyPropertyChanged. 

If the source object is a CLR object and the source property is a CLR property, the Windows Presentation 
Foundation (WPF) data binding engine has to first use reflection on the source object to get the TypeDescriptor, 
and then query for a PropertyDescriptor. This sequence of reflection operations is potentially very time- 
consuming from a performance perspective. 

The second method for resolving object references involves a CLR source object that implements the 
INotifyPropertyChanged interface, and a source property that is a CLR property. In this case, the data binding 
engine uses reflection directly on the source type and gets the required property. This is still not the optimal 
method, but it will cost less in working set requirements than the first method. 

The third method for resolving object references involves a source object that is a DependencyObject and a 
source property that is a DependencyProperty. In this case, the data binding engine does not need to use 
reflection. Instead, the property engine and the data binding engine together resolve the property reference 
independently. This is the optimal method for resolving object references used for data binding. 

The table below compares the speed of data binding the Text property of one thousand TextBlock elements using 
these three methods. 


BINDING THE TEXT PROPERTY OF A 

TEXTBLOCK 

BINDING TIME (MS) 

RENDER TIME -- INCLUDES BINDING 

(MS) 

To a property of a CLR object 

115 

314 




BINDING THE TEXT PROPERTY OF A 
TEXT BLOCK 


BINDING TIME (MS) 


RENDER TIME -- INCLUDES BINDING 
(MS) 


To a property of a CLR object which 115 305 

implements INotifyPropertyChanged 


To a DependencyProperty of a 90 263 

DependencyObJect. 


Binding to Large CLR Objects 

There is a significant performance impact when you data bind to a single CLR object with thousands of 
properties. You can minimize this impact by dividing the single object into multiple CLR objects with fewer 
properties. The table shows the binding and rendering times for data binding to a single large CLR object versus 
multiple smaller objects. 

DATA BINDING 1000 TEXTBLOCK RENDER TIME -- INCLUDES BINDING 

OBJECTS BINDING TIME (MS) (MS) 

To a CLR object with 1000 properties 950 1200 

To 1000 CLR objects with one property 115 314 


Binding to an ItemsSource 

Consider a scenario in which you have a CLR List<T> object that holds a list of employees that you want to 
display in a ListBox. To create a correspondence between these two objects, you would bind your employee list to 
the ItemsSource property of the ListBox. However, suppose you have a new employee joining your group. You 
might think that in order to insert this new person into your bound ListBox values, you would simply add this 
person to your employee list and expect this change to be recognized by the data binding engine automatically. 
That assumption would prove false; in actuality, the change will not be reflected in the ListBox automatically. This 
is because the CLR List<T> object does not automatically raise a collection changed event. In order to get the 
ListBox to pick up the changes, you would have to recreate your list of employees and re-attach it to the 
ItemsSource property of the ListBox. While this solution works, it introduces a huge performance impact. Each 
time you reassign the ItemsSource of ListBox to a new object, the ListBox first throws away its previous items and 
regenerates its entire list. The performance impact is magnified if your ListBox maps to a complex DataTemplate. 

A very efficient solution to this problem is to make your employee list an ObservableCollection<T>. An 
ObservableCollection<T> object raises a change notification which the data binding engine can receive. The 
event adds or removes an item from an ItemsControl without the need to regenerate the entire list. 

The table below shows the time it takes to update the ListBox (with Ul virtualization turned off) when one item is 
added. The number in the first row represents the elapsed time when the CLR List<T> object is bound to ListBox 
element's ItemsSource. The number in the second row represents the elapsed time when an 
ObservableCollection<T> is bound to the ListBox element's ItemsSource. Note the significant time savings using 
the ObservableCollection<T> data binding strategy. 

DATA BINDING THE ITEMSSOURCE UPDATE TIME FOR 1 ITEM (MS) 

To a CLR List<T> object 1656 


To an ObservableCollection<T> 


20 


Bind IList to ItemsControl not lEnumerable 


If you have a choice between binding an IList<T> or an lEnumerable to an ItemsControl object, choose the 
IList<T> object. Binding lEnumerable to an ItemsControl forces WPF to create a wrapper IList<T> object, which 
means your performance is impacted by the unnecessary overhead of a second object. 

Do not Convert CLR objects to XML Just for Data Binding. 

WPF allows you to data bind to XML content; however, data binding to XML content is slower than data binding 
to CLR objects. Do not convert CLR object data to XML if the only purpose is for data binding. 

See also 

• Optimizing WPF Application Performance 

• Planning for Application Performance 

• Taking Advantage of Hardware 

• Layout and Design 

• 2D Graphics and Imaging 

• Object Behavior 

• Application Resources 

• Text 

• Other Performance Recommendations 

• Data Binding Overview 

• Walkthrough: Caching Application Data in a WPF Application 
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Windows Presentation Foundation (WPF) includes many of the common user-interface (Ul) components that are 
used in most Windows applications. This topic contains techniques for improving the performance of your Ul. 

Displaying large data sets 

WPF controls such as the ListView and ComboBox are used to display lists of items in an application. If the list to 
display is large, the application's performance can be affected. This is because the standard layout system creates a 
layout container for each item associated with the list control, and computes its layout size and position. Typically, 
you do not have to display all the items at the same time; instead you display a subset, and the user scrolls through 
the list. In this case, it makes sense to use Ul virtualization, which means the item container generation and 
associated layout computation for an item is deferred until the item is visible. 

Ul Virtualization is an important aspect of list controls. Ul virtualization should not be confused with data 
virtualization. Ul virtualization stores only visible items in memory but in a data-binding scenario stores the entire 
data structure in memory. In contrast, data virtualization stores only the data items that are visible on the screen in 
memory. 

By default, Ul virtualization is enabled for the ListView and ListBox controls when their list items are bound to data. 
TreeView virtualization can be enabled by setting the VirtualizingStackPanel.lsVirtualizing attached property to 
true . If you want to enable Ul virtualization for custom controls that derive from ItemsControl or existing item 
controls that use the StackPanel class, such as ComboBox, you can set the ItemsPanel to VirtualizingStackPanel and 
set IsVirtualizing to true . Unfortunately, you can disable Ul virtualization for these controls without realizing it. 

The following is a list of conditions that disable Ul virtualization. 

• Item containers are added directly to the ItemsControl. For example, if an application explicitly adds 
ListBoxItem objects to a ListBox, the ListBox does not virtualize the ListBoxItem objects. 

• Item containers in the ItemsControl are of different types. For example, a Menu that uses Separator objects 
cannot implement item recycling because the Menu contains objects of type Separator and Menultem. 

• Setting CanContentScroll to false . 

• Setting IsVirtualizing to false. 

An important consideration when you virtualize item containers is whether you have additional state information 
associated with an item container that belongs with the item. In this case, you must save the additional state. For 
example, you might have an item contained in an Expander control and the IsExpanded state is bound to the item's 
container, and not to the item itself When the container is reused for a new item, the current value of IsExpanded is 
used for the new item. In addition, the old item loses the correct IsExpanded value. 

Currently, no WPF controls offer built-in support for data virtualization. 

Container recycling 

An optimization to Ul virtualization added in the .NET Framework 3.5 SP1 for controls that inherit from 
ItemsControl is container recyding, which can also improve scrolling performance. When an ItemsControl that uses 
Ul virtualization is populated, it creates an item container for each item that scrolls into view and destroys the item 
container for each item that scrolls out of view. Container recycling er\ab\es the control to reuse the existing item 
containers for different data items, so that item containers are not constantly created and destroyed as the user 








scrolls the ItemsControl. You can choose to enable item recycling by setting the VirtualizationMode attached 
property to Recycling. 

Any ItemsControl that supports virtualization can use container recycling. For an example of how to enable 
container recycling on a ListBox, see Improve the Scrolling Performance of a ListBox. 

Supporting bidirectional virtualization 

VirtualizingStackPanel offers built-in support for Ul virtualization in one direction, either horizontally or vertically. If 
you want to use bidirectional virtualization for your controls, you must implement a custom panel that extends the 
VirtualizingStackPanel class. The VirtualizingStackPanel class exposes virtual methods such as 
OnViewportSizeChanged, LineUp, PageUp, and MouseWheelUp.These virtual methods enable you to detect a 
change in the visible part of a list and handle it accordingly. 

Optimizing templates 

The visual tree contains all the visual elements in an application. In addition to the objects directly created, it also 
contains objects due to template expansion. For example, when you create a Button, you also get 
ClassicBorderDecorator and ContentPresenter objects in the visual tree. If you haven't optimized your control 
templates, you may be creating a lot of extra unnecessary objects in the visual tree. For more information on the 
visual tree, see WPF Graphics Rendering Overview. 

Deferred scrolling 

By default, when the user drags the thumb on a scrollbar, the content view continuously updates. If scrolling is slow 
in your control, consider using deferred scrolling. In deferred scrolling, the content is updated only when the user 
releases the thumb. 

To implement deferred scrolling, set the IsDeferredScrollingEnabled property to true . IsDeferredScrollingEnabled 
is an attached property and can be set on ScrollViewer and any control that has a ScrollViewer in its control 
template. 

Controls that implement performance features 

The following table lists the common controls for displaying data and their support of performance features. See 
the previous sections for information on how to enable these features. 


CONTROL 

VIRTUALIZATION 

CONTAINER RECYCLING 

DEEERRED SCROLLING 

ComboBox 

Can be enabled 

Can be enabled 

Can be enabled 

ContextMenu 

Can be enabled 

Can be enabled 

Can be enabled 

DocumentViewer 

Not available 

Not available 

Can be enabled 

ListBox 

Default 

Can be enabled 

Can be enabled 

ListView 

Default 

Can be enabled 

Can be enabled 

TreeView 

Can be enabled 

Can be enabled 

Can be enabled 

ToolBar 

Not available 

Not available 

Can be enabled 



NOTE 

For an example of how to enable virtualization and container recycling on a TreeView, see Improve the Performance of a 
TreeView. 


See also 

• Layout 

• Layout and Design 

• Data Binding 

• Controls 

• Styling and Templating 

• Walkthrough: Caching Application Data in a WPF Application 
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This topic provides performance recommendations in addition to the ones covered by the topics in the 
Optimizing WPF Application Performance section. 

This topic contains the following sections: 

• Opacity on Brushes Versus Opacity on Elements 

• Navigation to Object 

• Hit Testing on Large 3D Surfaces 

• CompositionTarget.Rendering Event 

• Avoid Using ScrollBarVisibility=Auto 

• Configure Font Cache Service to Reduce Start-up Time 

Opacity on Brushes Versus Opacity on Elements 

When you use a Brush to set the Fill or Stroke of an element, it is better to set the Brush.Opacity value rather than 
the setting the element's Opacity property. Modifying an element's Opacity property can cause WPF to create a 
temporary surface. 

Navigation to Object 

The NavigationWindow object derives from Window and extends it with content navigation support, primarily by 
aggregating NavigationService and the journal. You can update the client area of NavigationWindow by 
specifying either a uniform resource identifier (URI) or an object. The following sample shows both methods: 

private void buttonGoToUri(object sender, RoutedEventArgs args) 

{ 

navWindow.Source = new Uri("NewPage.xaml", UriKind.RelativeOrAbsolute); 

} 

private void buttonGoNewObject(object sender, RoutedEventArgs args) 

{ 

NewPage nextPage = new IMewPage(); 
next Page. InitializeComponentO; 
navWindow.Content = nextPage; 

} 


Private Sub buttonGoToLlri(ByVal sender As Object, ByVal args As RoutedEventArgs) 
navWindow.Source = IMew Uri("NewPage.xaml", UriKind.RelativeOrAbsolute) 

End Sub 

Private Sub buttonGoNewObject(ByVal sender As Object, ByVal args As RoutedEventArgs) 
Dim nextPage As New NewPage() 
next Page. InitializeComponentO 
navWindow.Content = nextPage 
End Sub 


Each NavigationWindow object has a journal that records the user's navigation history in that window. One of 





the purposes of the journal is to allow users to retrace their steps. 

When you navigate using a uniform resource identifier (URI), thejournal stores only the uniform resource 
identifier (URI) reference. This means that each time you revisit the page, it is dynamically reconstructed, which 
may be time consuming depending on the complexity of the page. In this case, thejournal storage cost is low, but 
the time to reconstitute the page is potentially high. 

When you navigate using an object, thejournal stores the entire visual tree of the object. This means that each 
time you revisit the page, it renders immediately without having to be reconstructed. In this case, thejournal 
storage cost is high, but the time to reconstitute the page is low. 

When you use the NavigationWindow object, you will need to keep in mind how the journaling support impacts 
your application's performance. For more information, see Navigation Overview. 

Hit Testing on Large 3D Surfaces 

Hit testing on large 3D surfaces is a very performance intensive operation in terms of CPU consumption. This is 
especially true when the 3D surface is animating. If you do not require hit testing on these surfaces, then disable 
hit testing. Objects that are derived from UlElement can disable hit testing by setting the IsHitTestVisible property 
to false . 

CompositionTarget.Rendering Event 

The CompositionTarget.Rendering event causes WPF to continuously animate. If you use this event, detach it at 
every opportunity. 

Avoid Using ScrollBarVisibility=Auto 

Whenever possible, avoid using the ScrollBarVisibility.Auto value for the HorizontaiscroiiBarVisibiiity and 
verticaiscroiiBarVisibiiity properties. These properties are defined for RichTextBox, ScrollViewer, and TextBox 
objects, and as an attached property for the ListBox object. Instead, set ScrollBarVisibility to Disabled, Hidden, or 
Visible. 

The Auto value is intended for cases when space is limited and scrollbars should only be displayed when 
necessary. For example, it may be useful to use this ScrollBarVisibility value with a ListBox of 30 items as 
opposed to a TextBox with hundreds of lines of text. 

Configure Font Cache Service to Reduce Start-up Time 

The WPF Font Cache service shares font data between WPF applications. The first WPF application you run starts 
this service if the service is not already running. If you are using Windows Vista, you can set the "Windows 
Presentation Foundation (WPF) Font Cache 3.0.0.0" service from "Manual" (the default) to "Automatic (Delayed 
Start)" to reduce the initial start-up time of WPF applications. 

See also 

• Planning for Application Performance 

• Taking Advantage of Hardware 

• Layout and Design 

• 2D Graphics and Imaging 

• Object Behavior 

• Application Resources 

• Text 

• Data Binding 
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Application Startup Time 
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The amount of time that is required for a WPF application to start can vary greatly. This topic describes various 
techniques for reducing the perceived and actual startup time for a Windows Presentation Foundation (WPF) 
application. 

Understanding Cold Startup and Warm Startup 

Cold startup occurs when your application starts for the first time after a system reboot, or when you start your 
application, close it, and then start it again after a long period of time. When an application starts, if the required 
pages (code, static data, registry, etc) are not present in the Windows memory manager's standby list, page faults 
occur. Disk access is required to bring the pages into memory. 

Warm startup occurs when most of the pages for the main common language runtime (CLR) components are 
already loaded in memory, which saves expensive disk access time. That is why a managed application starts faster 
when it runs a second time. 

Implement a Splash Screen 

In cases where there is a significant, unavoidable delay between starting an application and displaying the first Ul, 
optimize the perceived startup time by using a splash screen. This approach displays an image almost immediately 
after the user starts the application. When the application is ready to display its first Ul, the splash screen fades. 
Starting in the .NET Framework 3.5 SP1, you can use the SplashScreen class to implement a splash screen. For 
more information, see Add a Splash Screen to a WPF Application. 

You can also implement your own splash screen by using native Win32 graphics. Display your implementation 
before the Run method is called. 

Analyze the Startup Code 

Determine the reason for a slow cold startup. Disk I/O may be responsible, but this is not always the case. In 
general, you should minimize the use of external resources, such as network, Web services, or disk. 

Before you test, verify that no other running applications or services use managed code or WPF code. 

Start your WPF application immediately after a reboot, and determine how long it takes to display. If all subsequent 
launches of your application (warm startup) are much faster, your cold startup issue is most likely caused by I/O. 

If your application's cold startup issue is not related to I/O, it is likely that your application performs some lengthy 
initialization or computation, waits for some event to complete, or requires a lot of JIT compilation at startup. The 
following sections describe some of these situations in more detail. 

Optimize Module Loading 

Use tools such as Process Explorer (Procexp.exe) and Tlist.exe to determine which modules your application loads. 
The command Tiist <pid> shows all the modules that are loaded by a process. 

For example, if you are not connecting to the Web and you see that System.Web.dll is loaded, then there is a 
module in your application that references this assembly. Check to make sure that the reference is necessary. 

If your application has multiple modules, merge them into a single module. This approach requires less CLR 




assembly-loading overhead. Fewer assemblies also mean that the CLR maintains less state. 

Defer Initialization Operations 

Consider postponing initialization code until after the main application window is rendered. 

Be aware that initialization may be performed inside a class constructor, and if the initialization code references 
other classes, it can cause a cascading effect in which many class constructors are executed. 

Avoid Application Configuration 

Consider avoiding application configuration. For example, if an application has simple configuration requirements 
and has strict startup time goals, registry entries or a simple INI file may be a faster startup alternative. 

Utilize the GAC 

If an assembly is not installed in the Global Assembly Cache (GAC), there are delays caused by hash verification of 
strong-named assemblies and by Ngen image validation if a native image for that assembly is available on the 
computer. Strong-name verification is skipped for all assemblies installed in the GAC. For more information, see 
Gacutil.exe (Global Assembly Cache Tool). 

Use Ngen.exe 

Consider using the Native Image Generator (Ngen.exe) on your application. Using Ngen.exe means trading CPU 
consumption for more disk access because the native image generated by Ngen.exe is likely to be larger than the 
MSIL image. 

To improve the warm startup time, you should always use Ngen.exe on your application, because this avoids the 
CPU cost of JIT compilation of the application code. 

In some cold startup scenarios, using Ngen.exe can also be helpful. This is because the JIT compiler (mscorjit.dll) 
does not have to be loaded. 

Having both Ngen and JIT modules can have the worst effect. This is because mscorjit.dll must be loaded, and when 
the JIT compiler works on your code, many pages in the Ngen images must be accessed when the JIT compiler 
reads the assemblies' metadata. 

Ngen and ClickOnce 

The way you plan to deploy your application can also make a difference in load time. ClickOnce application 
deployment does not support Ngen. If you decide to use Ngen.exe for your application, you will have to use 
another deployment mechanism, such as Windows Installer. 

For more information, see Ngen.exe (Native Image Generator). 

Rebasing and DLL Address Collisions 

If you use Ngen.exe, be aware that rebasing can occur when the native images are loaded in memory. If a DLL is 
not loaded at its preferred base address because that address range is already allocated, the Windows loader will 
load it at another address, which can be a time-consuming operation. 

You can use the Virtual Address Dump (Vadump.exe) tool to check if there are modules in which all the pages are 
private. If this is the case, the module may have been rebased to a different address. Therefore, its pages cannot be 
shared. 

For more information about how to set the base address, see Ngen.exe (Native Image Generator). 


Optimize Authenticode 


Authenticode verification adds to the startup time. Authenticode-signed assemblies have to be verified with the 
certification authority (CA). This verification can be time consuming, because it can require connecting to the 
network several times to download current certificate revocation lists. It also makes sure that there is a full chain of 
valid certificates on the path to a trusted root. This can translate to several seconds of delay while the assembly is 
being loaded. 

Consider installing the CA certificate on the client computer, or avoid using Authenticode when it is possible. If you 
know that your application does not need the publisher evidence, you do not have to pay the cost of signature 
verification. 

Starting in .NET Framework 3.5, there is a configuration option that allows the Authenticode verification to be 
bypassed. To do this, add the following setting to the app.exe.config file: 

<configuration> 

<runtime> 

<generatePublisherEvidence enabled="false"/> 

</runtime> 

</configur'ation> 

For more information, see <generatePublisherEvidence> Element. 

Compare Performance on Windows Vista 

The memory manager in Windows Vista has a technology called SuperFetch. SuperFetch analyzes memory usage 
patterns over time to determine the optimal memory content for a specific user. It works continuously to maintain 
that content at all times. 

This approach differs from the pre-fetch technique used in Windows XR which preloads data into memory without 
analyzing usage patterns. Over time, if the user uses your WPF application frequently on Windows Vista, the cold 
startup time of your application may improve. 

Use AppDomains Efficiently 

If possible, load assemblies into a domain-neutral code area to make sure that the native image, if one exists, is 
used in all AppDomains created in the application. 

For the best performance, enforce efficient cross-domain communication by reducing cross-domain calls. When 
possible, use calls without arguments or with primitive type arguments. 

Use the NeutralResourcesLanguage Attribute 

Use the NeutralResourcesLanguageAttribute to specify the neutral culture for the ResourceManager. This approach 
avoids unsuccessful assembly lookups. 

Use the BinaryFormatter Class for Serialization 

If you must use serialization, use the BinaryFormatter class instead of the XmlSerializer class. The BinaryFormatter 
class is implemented in the Base Class Library (BCL) in the mscorlib.dll assembly. The XmlSerializer is implemented 
in the System.Xml.dll assembly, which might be an additional DLL to load. 

If you must use the XmlSerializer class, you can achieve better performance if you pre-generate the serialization 
assembly. 

Configure ClickOnce to Check for Updates After Startup 

If your application uses ClickOnce, avoid network access on startup by configuring ClickOnce to check the 



deployment site for updates after the application starts. 


If you use the XAML browser application (XBAP) model, keep in mind that ClickOnce checks the deployment site for 
updates even if the XBAP is already in the ClickOnce cache. For more information, see ClickOnce Security and 
Deployment. 

Configure the PresentationFontCache Service to Start Automatically 

The first WPF application to run after a reboot is the PresentationFontCache service. The service caches the system 
fonts, improves font access, and improves overall performance. There is an overhead in starting the service, and in 
some controlled environments, consider configuring the service to start automatically when the system reboots. 

Set Data Binding Programmatically 

Instead of using XAML to set the DataContext declaratively for the main window, consider setting it 
programmatically in the OnActivated method. 

See also 

• SplashScreen 

• AppDomain 

• Neutral ResourcesLanguageAttribute 

• ResourceManager 

• Add a Splash Screen to a WPF Application 

• Ngen.exe (Native Image Generator) 

• <generatePublisherEvidence> Element 


Walkthrough; Caching Application Data in a WPF 
Application 
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Caching enables you to store data in memory for rapid access. When the data is accessed again, applications can 
get the data from the cache instead of retrieving it from the original source. This can improve performance and 
scalability. In addition, caching makes data available when the data source is temporarily unavailable. 

The .NET Framework provides classes that enable you to use caching in .NET Framework applications. These 
classes are located in the System.Runtime.Caching namespace. 


NOTE 

The System.Runtime.Caching namespace is new in the .NET Framework 4. This namespace makes caching is available to all 
.NET Framework applications. In previous versions of the .NET Framework, caching was available only in the System.Web 
namespace and therefore required a dependency on ASRNET classes. 


This walkthrough shows you how to use the caching functionality that is available in the .NET Framework as part 
of a Windows Presentation Foundation (WPF) application. In the walkthrough, you cache the contents of a text file. 

Tasks illustrated in this walkthrough include the following: 

• Creating a WPF application project. 

• Adding a reference to the .NET Framework 4. 

• Initializing a cache. 

• Adding a cache entry that contains the contents of a text file. 

• Providing an eviction policy for the cache entry. 

• Monitoring the path of the cached file and notifying the cache instance about changes to the monitored 
item. 

Prerequisites 

In order to complete this walkthrough, you will need: 

• Visual Studio 2010. 

• A text file that contains a small amount of text. (You will display the contents of the text file in a message 
box.) The code illustrated in the walkthrough assumes that you are working with the following file: 

c:\cache\cacheText.txt 

However, you can use any text file and make small changes to the code in this walkthrough. 

Creating a WPF Application Project 

You will start by creating a WPF application project. 

To create a WPF application 

1. Start Visual Studio. 






2. In the File menu, click New, and then click New Project. 

The New Project dialog box is displayed. 

3. Under Installed Templates, select the programming language you want to use (Visual Basic or Visual 
C#). 

4. In the New Project dialog box, select WPF Application. 

NOTE 

If you do not see the WPF Application template, make sure that you are targeting a version of the .NET 
Framework that supports WPF. In the New Project dialog box, select .NET Framework 4 from the list. 

5. In the Name text box, enter a name for your project. For example, you can enter WPFCaching. 

6. Select the Create directory for solution checkbox. 

7. Click OK. 

The WPF Designer opens in Design view and displays the MainWindow.xamI file. Visual Studio creates the 
My Project folder, the Application.xamI file, and the MainWindow.xamI file. 

Targeting the .NET Framework and Adding a Reference to the Caching 
Assemblies 

By default, WPF applications target the .NET Framework 4 Client Profile. To use the System.Runtime.Caching 
namespace in a WPF application, the application must target the .NET Framework 4 (not the .NET Framework 4 
Client Profile) and must include a reference to the namespace. 

Therefore, the next step is to change the .NET Framework target and add a reference to the 
System.Runtime.Caching namespace. 


NOTE 

The procedure for changing the .NET Framework target is different in a Visual Basic project and in a Visual C# project. 


To change the target .NET Framework in Visual Basic 

1. In Solutions Explorer, right-click the project name, and then click Properties. 

The properties window for the application is displayed. 

2. Click the Compile tab. 

3. At the bottom of the window, click Advanced Compile Options.... 

The Advanced Compiler Settings dialog box is displayed. 

4. In the Target framework (all configurations) list, select .NET Framework 4. (Do not select .NET 
Framework 4 Client Profile.) 

5. Click OK. 

The Target Framework Change dialog box is displayed. 

6. In the Target Framework Change dialog box, click Yes. 


The project is closed and is then reopened. 




7. Add a reference to the caching assembly by following these steps: 

a. In Solution Explorer, right-click the name of the project and then click Add Reference. 

b. Selectthe.NET tab, select System.Runtime.Caching , and then click OK. 

To change the target .NET Framework in a Visual C# project 

1. In Solution Explorer, right-click the project name and then click Properties. 

The properties window for the application is displayed. 

2. Click the Application tab. 

3. In the Target framework list, select .NET Framework 4. (Do not select .NET Framework 4 Client 
Profile.) 

4. Add a reference to the caching assembly by following these steps: 

a. Right-click the References folder and then click Add Reference. 

b. Selectthe.NET tab, select System.Runtime.Caching , and then click OK. 

Adding a Button to the WPF Window 

Next, you will add a button control and create an event handler for the button's Click event. Later you will add 
code to so when you click the button, the contents of the text file are cached and displayed. 

To add a button control 

1. In Solution Explorer, double-click the MainWindow.xamI file to open it. 

2. From the Toolbox, under Common WPF Controls, drag a Button control tothe MainWindow window. 

3. In the Properties window, set the content property of the Button control to Get Cache. 

Initializing the Cache and Caching an Entry 

Next, you will add the code to perform the following tasks: 

• Create an instance of the cache class—that is, you will instantiate a new MemoryCache object. 

• Specify that the cache uses a HostFileChangeMonitor object to monitor changes in the text file. 

• Read the text file and cache its contents as a cache entry. 

• Display the contents of the cached text file. 

To create the cache object 

1. Double-click the button you just added in order to create an event handler in the MainWindow.xaml.es or 
MainWindow.Xaml.vb file. 

2. At the top of the file (before the class declaration), add the following imports (Visual Basic) or using (C#) 
statements: 


using System.Runtime.Caching; 
using System.10; 


Imports System.Runtime.Caching 
Imports System.10 












3. In the event handler, add the following code to instantiate the cache object: 


ObjectCache cache = MemoryCache.Default; 

Dim cache As OhjectCache = MemoryCache.Default 

The ObjectCache class is a built-in class that provides an in-memory object cache. 

4. Add the following code to read the contents of a cache entry named fiiecontents : 

Dim fileContents As String = TryCast(cache("filecontents")j String) 

string fileContents = cache["filecontents"] as string; 

5. Add the following code to check whether the cache entry named fiiecontents exists: 

If fileContents Is Mothing Then 
End If 

if (fileContents == null) 

{ 

} 

If the specified cache entry does not exist, you must read the text file and add it as a cache entry to the 
cache. 

6. In the if/then block, add the following code to create a new CacheltemPolicy object that specifies that the 
cache entry expires after 10 seconds. 

Dim policy As New CacheltemPolicyO 

policy.AhsoluteExpiration = DateTimeOffset.Now.AddSeconds(10.0) 


CacheltemPolicy policy = new CacheltemPolicyO; 

policy.AhsoluteExpiration = DateTimeOffset.Now.AddSeconds(10.0); 

If no eviction or expiration information is provided, the default is InfiniteAbsoluteExpiration, which means 
the cache entries never expire based only on an absolute time. Instead, cache entries expire only when there 
is memory pressure. As a best practice, you should always explicitly provide either an absolute or a sliding 
expiration. 

7. Inside the if/then block and following the code you added in the previous step, add the following code to 
create a collection for the file paths that you want to monitor, and to add the path of the text file to the 
collection: 

Dim filePaths As New List(0f String)() 
filePaths.Add("c:\cache\cacheText.txt") 










List<str'ing> filePaths = new List<string>(); 
filePaths.Add("c:\\cache\\cacheText.txt"); 


NOTE 

If the text file you want to use is not c: \cache\cacheText.txt , specify the path where the text file is that you want 
to use. 


8. Following the code that you added in the previous step, add the following code to add a new 
HostFileChangeMonitor object to the collection of change monitors for the cache entry: 

policy.ChangeHonitons.Add(New HostFileChangeMonitor(filePaths)) 

policy.ChangeHonitons.Add(new HostFileChangeMonitor(filePaths)); 

The HostFileChangeMonitor object monitors the text file's path and notifies the cache if changes occur. In 
this example, the cache entry will expire if the content of the file changes. 

9. Following the code that you added in the previous step, add the following code to read the contents of the 
text file: 

fileContents = File.ReadAllText("c:\cache\cacheText.txt") & vbCnLf & DateTime.Now.ToStringO 

fileContents = File.ReadAllText("c:\\cache\\cacheText .txt") + "\n" + DateTime.Now; 

The date and time timestamp is added so that you will be able to see when the cache entry expires. 

10. Following the code that you added in the previous step, add the following code to insert the contents of the 
file into the cache object as a Cacheltem instance: 

cache.Set("filecontents"^ fileContents, policy) 

cache.Set("filecontents", fileContents, policy); 

You specify information about how the cache entry should be evicted by passing the Cacheltem Policy object 
that you created earlier as a parameter. 

11. After the if/then block, add the following code to display the cached file content in a message box: 

MessageBox.Show(fileContents) 

MessageBox.Show(fileContents); 

12. In the Build menu, click Build WPFCaching to build your project. 


Testing Caching in the WPF Application 








You can now test the application. 

To test caching in the WPF application 

1. Press CTRL+F5 to run the application. 


The MainWindow window is displayed. 

2. Click Get Cache. 

The cached content from the text file is displayed in a message box. Notice the timestamp on the file. 

3. Close the message box and then click Get Cache again. 

The timestamp is unchanged. This indicates the cached content is displayed. 

4. Wait 10 seconds or more and then click Get Cache again. 

This time a new timestamp is displayed. This indicates that the policy let the cache entry expire and that 
new cached content is displayed. 

5. In a text editor, open the text file that you created. Do not make any changes yet. 

6. Close the message box and then click Get Cache again. 

Notice the timestamp again. 

7. Make a change to the text file and then save the file. 

8. Close the message box and then click Get Cache again. 

This message box contains the updated content from the text file and a new timestamp. This indicates that 
the host-file change monitor evicted the cache entry immediately when you changed the file, even though 
the absolute timeout period had not expired. 

NOTE 

You can increase the eviction time to 20 seconds or more to allow more time for you to make a change in the file. 


Code Example 

After you have completed this walkthrough, the code for the project you created will resemble the following 
example. 




using System; 

using System.Collections.Generic; 
using System.Linq; 
using System.Text; 
using System.Windows; 
using System.Windows.Controls; 
using System.Windows.Data; 
using System.Windows.Documents; 
using System.Windows.Input; 
using System.Windows.Media; 
using System.Windows.Media.Imaging; 
using System.Windows.Navigation; 
using System.Windows.Shapes; 
using System.Runtime.Caching; 
using System.ID; 

namespace WPFCaching 

{ 

III <summary> 

III Interaction logic for MainWindow.xaml 
III </summary> 

public partial class MainWindow : Window 

{ 

public MainWindowO 

{ 

InitializeComponent(); 

} 

private void buttonl_Click(object sender^ RoutedEventArgs e) 

{ 

ObjectCache cache = MemoryCache.Default; 

string fileContents = cache["filecontents"] as string; 

if (fileContents == null) 

{ 

CacheltemPolicy policy = new CacheltemPolicyO; 
policy.AbsoluteExpiration = 

DateTimeOffset.Now.AddSeconds(10.0); 

List<string> filePaths = new List<string>(); 
filePaths.Add("c:\\cache\\cacheText.txt"); 

policy.ChangeMonitors.Add(new 

HostFileChangeMonitor(filePaths)); 

// Fetch the file contents. 

fileContents = File.ReadAllText("c:\\cache\\cacheText.txt") + "\n" + DateTime.Now.ToStringO; 
cache.Set("filecontents", fileContents^ policy); 

} 

MessageBox.Show(fileContents); 

} 

} 

} 



Imports System.Runtime.Caching 
Imports System.10 

Class MainWindow 

Private Sub Buttonl_Click(By\/al sender As System.Object, ByVal e As System.Windows.RoutedEventArgs) 
Handles Buttonl.Click 

Dim cache As ObjectCache = MemoryCache.Default 

Dim fileContents As String = TryCast(cache("filecontents"), _ 

String) 

If fileContents Is Nothing Then 

Dim policy As New CacheltemPolicyO 
policy.AbsoluteExpiration = _ 

DateTimeOffset.Now.AddSeconds(10.0) 

Dim filePaths As New List(0f String)() 
filePaths.Add("c:\cache\cacheText.txt") 
policy.ChangeMonitors.Add(New _ 

HostFileChangeMonitor(filePaths)) 

' Fetch the file contents. 

fileContents = File.ReadAllText("c:\cache\cacheText.txt") & vbCrLf & DateTime.Now.ToStringO 
cache.Set("filecontents", fileContents, policy) 

End If 

MessageBox.Show(fileContents) 

End Sub 
End Class 


See also 

• MemoryCache 

• ObjectCache 

• System.Runtime.Caching 

• Caching in .NET Framework Applications 
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Windows Presentation Foundation (WPF) is designed to save developers from the difficulties of threading. As a 
result, the majority of WPF developers won't have to write an interface that uses more than one thread. Because 
multithreaded programs are complex and difficult to debug, they should be avoided when single-threaded 
solutions exist. 

No matter how well architected, however, no Ul framework will ever be able to provide a single-threaded 
solution for every sort of problem. WPF comes close, but there are still situations where multiple threads 
improve user interface (Ul) responsiveness or application performance. After discussing some background 
material, this paper explores some of these situations and then concludes with a discussion of some lower-level 
details. 


NOTE 

This topic discusses threading by using the Begininvoke method for asynchronous calls. You can also make asynchronous 
calls by calling the InvokeAsync method, which take an Action or Func<TResult> as a parameter. The InvokeAsync method 
returns a DispatcherOperation or DispatcherOperation<TResult>, which has a Task property. You can use the await 
keyword with either the DispatcherOperation or the associated Task. If you need to wait synchronously for the Task that is 
returned by a DispatcherOperation or DispatcherOperation<TResult>, call the DispatcherOperationWait extension method. 
Calling Task.Wait will result in a deadlock. For more information about using a Task to perform asynchronous operations, 
see Task Parallelism. The Invoke method also has overloads that take an Action or Func<TResult> as a parameter. You can 
use the Invoke method to make synchronous calls by passing in a delegate. Action or Func<TResult>. 


Overview and the Dispatcher 

Typically, WPF applications start with two threads: one for handling rendering and another for managing the Ul. 
The rendering thread effectively runs hidden in the background while the Ul thread receives input, handles 
events, paints the screen, and runs application code. Most applications use a single Ul thread, although in some 
situations it is best to use several. We'll discuss this with an example later. 

The Ul thread queues work items inside an object called a Dispatcher. The Dispatcher selects work items on a 
priority basis and runs each one to completion. Every Ul thread must have at least one Dispatcher, and each 
Dispatcher can execute work items in exactly one thread. 

The trick to building responsive, user-friendly applications is to maximize the Dispatcher throughput by keeping 
the work items small. This way items never get stale sitting in the Dispatcher queue waiting for processing. Any 
perceivable delay between input and response can frustrate a user. 

How then are WPF applications supposed to handle big operations? What if your code involves a large 
calculation or needs to query a database on some remote server? Usually, the answer is to handle the big 
operation in a separate thread, leaving the Ul thread free to tend to items in the Dispatcher queue. When the big 
operation is complete, it can report its result back to the Ul thread for display. 

Historically, Windows allows Ul elements to be accessed only by the thread that created them. This means that a 
background thread in charge of some long-running task cannot update a text box when it is finished. Windows 
does this to ensure the integrity of Ul components. A list box could look strange if its contents were updated by a 
background thread during painting. 


WPF has a built-in mutual exclusion mechanism that enforces this coordination. Most classes in WPF derive from 





DispatcherObject. At construction, a DispatcherObject stores a reference to the Dispatcher linked to the currently 
running thread. In effect, the DispatcherObject associates with the thread that creates it. During progrann 
execution, a DispatcherObject can call its public VerifyAccess method. VerifyAccess examines the Dispatcher 
associated with the current thread and compares it to the Dispatcher reference stored during construction. If they 
don't match, VerifyAccess throws an exception. VerifyAccess is intended to be called at the beginning of every 
method belonging to a DispatcherObject. 

If only one thread can modify the Ul, how do background threads interact with the user? A background thread 
can ask the Ul thread to perform an operation on its behalf. It does this by registering a work item with the 
Dispatcher of the Ul thread. The Dispatcher class provides two methods for registering work items: Invoke and 
Begininvoke. Both methods schedule a delegate for execution. Invoke is a synchronous call - that is, it doesn't 
return until the Ul thread actually finishes executing the delegate. Begininvoke is asynchronous and returns 
immediately. 

The Dispatcher orders the elements in its queue by priority. There are ten levels that may be specified when 
adding an element to the Dispatcher queue. These priorities are maintained in the DispatcherPriority 
enumeration. Detailed information about DispatcherPriority levels can be found in the Windows SDK 
documentation. 

Threads in Action: The Samples 

A Single-Threaded Application with a Long-Running Calculation 

Most graphical user interfaces (GUIs) spend a large portion of their time idle while waiting for events that are 
generated in response to user interactions. With careful programming this idle time can be used constructively, 
without affecting the responsiveness of the Ul. The WPF threading model doesn't allow input to interrupt an 
operation happening in the Ul thread. This means you must be sure to return to the Dispatcher periodically to 
process pending input events before they get stale. 

Consider the following example: 



Click stop 



Click start 



Click Resume 


This simple application counts upwards from three, searching for prime numbers. When the user clicks the Start 
button, the search begins. When the program finds a prime, it updates the user interface with its discovery. At 
any point, the user can stop the search. 

Although simple enough, the prime number search could go on forever, which presents some difficulties. If we 
handled the entire search inside of the click event handler of the button, we would never give the Ul thread a 
chance to handle other events. The Ul would be unable to respond to input or process messages. It would never 
repaint and never respond to button clicks. 

We could conduct the prime number search in a separate thread, but then we would need to deal with 
synchronization issues. With a single-threaded approach, we can directly update the label that lists the largest 





















prime found. 


If we break up the task of calculation into manageable chunks, we can periodically return to the Dispatcher and 
process events. We can give WPF an opportunity to repaint and process input. 

The best way to split processing time between calculation and event handling is to manage calculation from the 
Dispatcher. By using the Begininvoke method, we can schedule prime number checks in the same queue that Ul 
events are drawn from. In our example, we schedule only a single prime number check at a time. After the prime 
number check is complete, we schedule the next check immediately. This check proceeds only after pending Ul 
events have been handled. 


Dispatcher Queue 


Repaint 


Mouse Move 
Mouse Enter 


checkNext Number 


Repaint 


Mouse Move 
Mouse Enter 



CheckNextNumber 

Iftnumber Is prime) 
update User Interface 

Nuiiiber+=2 

If(Continue) 

Add CheckNextNumber 
to dispatcher queue 


Microsoft Word accomplishes spell checking using this mechanism. Spell checking is done in the background 
using the idle time of the Ul thread. Let's take a look at the code. 

The following example shows the XAML that creates the user interface. 

cWindow x:Class="SDKSamples.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 

Tltle="Prlme Numbers" Width="260" Height="75" 

> 

cStackPanel Orientation="Horizontal" VerticalAlignment="Center" > 
cButton Content="Start" 

Click="StartOrStop" 

Name="startStopButton" 

Margin="5j0j5j0" 

/> 

cTextBlock Margin="10j5j0j0">Biggest Prime Found:</TextBlock> 
cTextBlock Name="bigPrime" Margin="4,5j0j0">3</TextBlock> 

</StackPanel> 

</Window> 


The following example shows the code-behind. 

using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Threading; 

using System.Threading; 

namespace SDKSamples 

{ 

public partial class Windowl : Window 

{ 

public delegate void NextPrimeDelegate(); 

//Current number to check 
private long num = 3; 


private bool continueCalculating = false; 



















public WindowlO : base() 

{ 

InitializeComponent(); 

} 

private void StartOrStop(object sender^ EventArgs e) 

{ 

if (continueCalculating) 

{ 

continueCalculating = false; 
startStopButton.Content = "Resume"; 

} 

else 

{ 

continueCalculating = true; 

StartStopButton.Content = "Stop"; 

StartStopButton.Dispatcher.BeginInvoke( 

DispatcherPriority.Normalj 

new NextPrimeDelegate(CheckNextNumber)); 

} 

} 

public void CheckNextNumber() 

{ 

// Reset flag. 

NotAPrime = false; 

for (long i = 3; i <= Math.Sqrt(num); i++) 

{ 

if (num % i == 0) 

{ 

// Set not a prime flag to true. 

NotAPrime = true; 
break; 

} 

} 

// If a prime number, 
if (!NotAPrime) 

{ 

bigPrime.Text = num.ToStringO; 

} 

num += 2; 

if (continueCalculating) 

{ 

StartStopButton.Dispatcher.BeginInvoke( 

System.Windows.Threading.DispatcherPriority.Systemidlej 
new NextPrimeDelegate(this.CheckNextNumber)); 

} 


private bool NotAPrime = false; 

} 

} 


Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Threading 
Imports System.Threading 

Namespace SDKSamples 

Partial Public Class MainWindow 
Inherits Window 

Public Delegate Sub NextPrimeDelegate() 

'Current number to check 
Private num As Long = 3 

Private continueCalculating As Boolean = False 

Public Sub New() 

MyBase.NewO 
InitializeComponent() 

End Sub 

Private Sub StartOrStop(ByVal sender As Object^ ByVal e As EventArgs) 

If continueCalculating Then 

continueCalculating = False 
startStopButton.Content = "Resume" 

Else 

continueCalculating = True 
StartStopButton.Content = "Stop" 

StartStopButton.Dispatcher.BeginInvoke(DispatcherPriority.Normalj New 
NextPrimeDelegate(AddressOf CheckNextNumber)) 

End If 
End Sub 

Public Sub CheckNextNumberO 
' Reset flag. 

NotAPrime = False 

For i As Long = 3 To Math.Sqrt(num) 

If num Mod i = 0 Then 

' Set not a prime flag to true. 

NotAPrime = True 
Exit For 
End If 

Next 

' If a prime number. 

If Not NotAPrime Then 

bigPrime.Text = num.ToStringO 
End If 

num += 2 

If continueCalculating Then 

startStopButton.Dispatcher.BeginInvoke(System.Windows.Threading.DispatcherPriority.Systemldle^ New 
NextPrimeDelegate(AddressOf Me.CheckNextNumber)) 

End If 
End Sub 

Private NotAPrime As Boolean = False 
End Class 
End Namespace 


The following example shows the event handler for the Button. 



private void StartOrStop(object sender, EventArgs e) 

{ 

if (continueCalculating) 

{ 

continueCalculating = false; 
startStopButton.Content = "Resume"; 

} 

else 

{ 

continueCalculating = true; 

StartStopButton.Content = "Stop"; 
StartStopButton.Dispatcher.BeginInvoke( 
DispatcherPriority.Normal, 
new NextPrimeDelegate(CheckNextNumber)); 

} 

} 


Private Sub StartOrStop(By\/al sender As Object, ByVal e As EventArgs) 

If continueCalculating Then 

continueCalculating = False 
StartStopButton.Content = "Resume" 

Else 

continueCalculating = True 
StartStopButton.Content = "Stop" 

startStopButton.Dispatcher.BeginInvoke(DispatcherPriority.Normal, New NextPrimeDelegate(AddressOf 
CheckNextNumber)) 

End If 
End Sub 


Besides updating the text on the Button, this handler is responsible for scheduling the first prime number check 
by adding a delegate to the Dispatcher queue. Sometime after this event handler has completed its work, the 
Dispatcher will select this delegate for execution. 

As we mentioned earlier, Begininvoke is the Dispatcher member used to schedule a delegate for execution. In this 
case, we choose the Systemidle priority. The Dispatcher will execute this delegate only when there are no 
important events to process. Ul responsiveness is more important than number checking. We also pass a new 
delegate representing the number-checking routine. 



public void CheckNextNumber() 

{ 

// Reset flag. 

NotAPnime = false; 

for (long i = 3; i <= Math.Sqrt(num); i++) 

{ 

if (num % i == 0) 

{ 

// Set not a prime flag to true. 

NotAPrime = true; 
break; 

} 

} 

// If a prime number, 
if (!NotAPrime) 

{ 

bigPrime.Text = num.ToStringO; 

} 

num += 2; 

if (continueCalculating) 

{ 

startStopButton.Dispatcher.BeginInvoke( 

System.Windows.Threading.DispatcherPriority.SystemIdlej 
new NextPrimeDelegate(this.CheckNextNumber)); 

} 

} 

private bool NotAPrime = false; 


Public Sub CheckNextNumberO 
' Reset flag. 

NotAPrime = False 

For i As Long = 3 To Math.Sqrt(num) 

If num Mod i = 0 Then 

' Set not a prime flag to true. 

NotAPrime = True 
Exit For 
End If 

Next 

' If a prime number. 

If Not NotAPrime Then 

bigPrime.Text = num.ToStringO 
End If 

num += 2 

If continueCalculating Then 

StartStopButton.Dispatcher.BeginInvoke(System.Windows.Threading.DispatcherPriority.Systemidle^ New 
NextPrimeDelegate(AddressOf Me.CheckNextNumber)) 

End If 
End Sub 

Private NotAPrime As Boolean = False 

This method checks if the next odd number is prime. If it is prime, the method directly updates the bigPrime 
TextBlock to reflect its discovery. We can do this because the calculation is occurring in the same thread that was 
used to create the component. Had we chosen to use a separate thread for the calculation, we would have to use 
a more complicated synchronization mechanism and execute the update in the Ul thread. We'll demonstrate this 
situation next. 




For the complete source code for this sample, see the Single-Threaded Application with Long-Running 
Calculation Sample 

Handling a Blocking Operation with a Background Thread 

Handling blocking operations in a graphical application can be difficult. We don't want to call blocking methods 
from event handlers because the application will appear to freeze up. We can use a separate thread to handle 
these operations, but when we're done, we have to synchronize with the Ul thread because we can't directly 
modify the GUI from our worker thread. We can use Invoke or Begininvoke to insert delegates into the 
Dispatcher of the Ul thread. Eventually, these delegates will be executed with permission to modify Ul elements. 

In this example, we mimic a remote procedure call that retrieves a weather forecast. We use a separate worker 
thread to execute this call, and we schedule an update method in the Dispatcher of the Ul thread when we're 
finished. 




Fetch Forecast 




Contacting Server 



i 



Fetch Forecast | 


i i i 

rainy 



] 


using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Media; 

using System.Windows.Media.Animation; 

using System.Windows.Media.Imaging; 

using System.Windows.Shapes; 

using System.Windows.Threading; 

using System.Threading; 

namespace SDKSamples 

{ 

public partial class Windowl : Window 

{ 

// Delegates to be used in placking jobs onto the Dispatcher. 

private delegate void NoArgDelegate(); 

private delegate void OneArgDelegate(String arg); 

// Storyboards for the animations, 
private Storyboard showClockFaceStoryboard; 
private Storyboard hideClockFaceStoryboard; 
private Storyboard showWeatherlmageStoryboard; 
private Storyboard hideWeatherlmageStoryboard; 

public Windowl(): base() 

{ 

InitializeComponentO: 






























} 


private void Window_Loaded(object sender^ RoutedEventArgs e) 

{ 

// Load the storyboard resources. 
showClockFaceStoryboard = 

(Storyboard)this.Resources["ShowClockFaceStoryboard"]; 
hideClockFaceStoryboard = 

(Storyboard )this. Resources ["FlideClockFaceStoryboard"]; 
showWeatherlmageStoryboard = 

(Storyboard)this.Resources["ShowWeatherlmageStoryboard"]j 
hideWeatherlmageStoryboard = 

(Story board) this. Resources [ "FlideWeatherlmageStoryboard" ]; 

} 

private void ForecastButtonFlandler(object sender^ RoutedEventArgs e) 

{ 

// Change the status image and start the rotation animation. 
fetchButton.IsEnabled = false; 
fetchButton.Content = "Contacting Server"; 
weatherText.Text = 

hideWeatherlmageStoryboard.Begin(this); 

// Start fetching the weather forecast asynchronously. 
NoArgDelegate fetcher = new NoArgDelegate( 
this.FetchWeatherFromServer); 

fetcher.BeginInvoke(null^ null); 

} 

private void FetchWeatherFromServer() 

{ 

// Simulate the delay from network access. 

Thread.Sleep(4000); 

// Tried and true method for weather forecasting - random numbers. 
Random rand = new Random(); 

String weather; 

if (rand.Next(2) == 0) 

{ 

weather = "rainy"; 

} 

else 

{ 

weather = "sunny"; 

} 

// Schedule the update function in the UI thread, 
tomorrowsWeather.Dispatcher.BeginInvoke( 

System.Windows.Threading.DispatcherPriority.Normalj 
new OneArgDelegate(UpdateLlserlnterface) j 
weather); 

} 

private void UpdateUserInterface(String weather) 

{ 

//Set the weather image 
if (weather == "sunny") 

{ 

weatherindicatorlmage.Source = (ImageSource)this.Resources[ 
"SunnylmageSource"]; 

} 

else if (weather == "rainy") 

{ 

weatherindicatorlmage.Source = (ImageSource)this.Resources[ 
"RaininglmageSource"]; 


} 


//stop clock animation 
showClockFaceStoryboard.Stop(this)j 
hideClockFaceStoryboard.Begin(this); 

//Update UI text 
fetchButton.IsEnabled = true; 
fetchButton.Content = "Fetch Forecast"; 
weatherText.Text = weather; 

} 

private void FlideClockFaceStoryboard_Completed(object sender^ 
EventArgs args) 

{ 

showWeatherlmageStoryboard.Begin(this); 

} 

private void FlideWeatherImageStoryboard_Completed(object sender, 
EventArgs args) 

{ 

showClockFaceStoryboard.Begin(this, true); 

} 

} 

} 


Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Media 
Imports System.Windows.Media.Animation 
Imports System.Windows.Media.Imaging 
Imports System.Windows.Shapes 
Imports System.Windows.Threading 
Imports System.Threading 

Namespace SDKSamples 

Partial Public Class Windowl 

Inherits Window 

' Delegates to be used in placking jobs onto the Dispatcher. 

Private Delegate Sub NoArgDelegate() 

Private Delegate Sub OneArgDelegate(ByVal arg As String) 

' Storyboards for the animations. 

Private showClockFaceStoryboard As Storyboard 

Private hideClockFaceStoryboard As Storyboard 

Private showWeatherlmageStoryboard As Storyboard 

Private hideWeatherlmageStoryboard As Storyboard 

Public Sub New() 

MyBase.New() 

InitializeComponent() 

End Sub 

Private Sub Wlndow_Loaded(By\/al sender As Object, ByVal e As RoutedEventArgs) 

' Load the storyboard resources. 

ShowClockFaceStoryboard = CType(Me.Resources("ShowClockFaceStoryboard"), Storyboard) 
hideClockFaceStoryboard = CType(Me.Resources("HideClockFaceStoryboard"), Storyboard) 
showWeatherlmageStoryboard = CType(Me.Resources("ShowWeatherlmageStoryboard"), Storyboard) 
hideWeatherlmageStoryboard = CType(Me.Resources("HideWeatherlmageStoryboard"), Storyboard) 

End Sub 

Private Sub ForecastButtonHandler(ByVal sender As Object, ByVal e As RoutedEventArgs) 

' Change the status image and start the rotation animation. 
fetchButton.IsEnabled = False 
fetchButton.Content = "Contacting Server" 
weatherText.Text = "" 
hideWeatherlmageStoryboard.Begin(Me) 


' start fetching the weather forecast asynchronously. 

Dim fetcher As New NoArgDelegate(AddressOf Me.FetchWeatherFromServer) 

fetcher. BeginInvol<e(Nothingj Nothing) 

End Sub 

Private Sub FetchWeatherFromServer() 

' Simulate the delay from network access. 

Thread.Sleep(4000) 

' Tried and true method for weather forecasting - random numbers. 

Dim rand As New Random() 

Dim weather As String 

If rand.Next(2) = 0 Then 
weather = "rainy" 

Else 

weather = "sunny" 

End If 

' Schedule the update function in the UI thread. 

tomorrowsWeather.Dispatcher.BeginInvoke(System.Windows.Threading.DispatcherPriority.Normalj New 
OneArgDelegate(AddressOf UpdateUserInterface), weather) 

End Sub 

Private Sub UpdateLlserInterface(ByVal weather As String) 

'Set the weather image 
If weather = "sunny" Then 

weatherindicatorlmage.Source = CType(Me.Resources("SunnyImageSource"), ImageSource) 

Elself weather = "rainy" Then 

weatherindicatorlmage.Source = CType(Me.Resources("RainingImageSource")j ImageSource) 

End If 

'Stop clock animation 
showClockFaceStoryboard.Stop(Me) 
hideClockFaceStoryboard.Begin(Me) 

'Update UI text 
fetchButton.IsEnabled = True 
fetchButton.Content = "Fetch Forecast" 
weatherText.Text = weather 
End Sub 

Private Sub FlideClockFaceStoryboard_Completed(ByVal sender As Object^ ByVal args As EventArgs) 
showWeatherlmageStoryboard.Begin(Me) 

End Sub 

Private Sub FlideWeatherImageStoryboard_Completed(ByVal sender As Object, ByVal args As EventArgs) 
ShowClockFaceStoryboard.Begin(Me, True) 

End Sub 
End Class 
End Namespace 


The following are some of the details to be noted. 


• Creating the Button Handler 


private void ForecastButtonHandler(object sendetj RoutedEventArgs e) 

{ 

// Change the status image and start the rotation animation. 
fetchButton.IsEnabled = false; 
fetchButton.Content = "Contacting Server"; 
weatherText.Text = 

hideWeatherlmageStoryboard.Begin(this); 

// Start fetching the weather forecast asynchronously. 
NoArgDelegate fetcher = new NoArgDelegate( 
this.FetchWeatherFromServer); 

fetcher.BeginInvol<e(nullj null); 

} 


Private Sub ForecastButtonHandler(By\/al sender As Object^ ByVal e As RoutedEventArgs) 
' Change the status image and start the rotation animation. 
fetchButton.IsEnabled = False 
fetchButton.Content = "Contacting Server" 
weatherText.Text = "" 
hideWeatherlmageStoryboard.Begin(Me) 

' Start fetching the weather forecast asynchronously. 

Dim fetcher As New NoArgDelegate(AddressOf Me.FetchWeatherFromServer) 

fetcher.BeginInvoke(Nothingj Nothing) 

End Sub 


When the button is clicked, we display the clock drawing and start animating it. We disable the button. We 
invoke the FetchWeatherFromServer method in a new thread, and then we return, allowing the Dispatcher to 
process events while we wait to collect the weather forecast. 

• Fetching the Weather 

private void FetchWeatherFromServer() 

{ 

// Simulate the delay from network access. 

Thread.Sleep(4000); 

// Tried and true method for weather forecasting - random numbers. 

Random rand = new Random(); 

String weather; 

if (rand.Next(2) == 0) 

{ 

weather = "rainy"; 

} 

else 

{ 

weather = "sunny"; 

} 

// Schedule the update function in the UI thread, 
tomorrowsWeather.Dispatcher.BeginInvoke( 

System.Windows.Threading.DispatcherPriority.Normalj 
new OneArgDelegate(UpdateUserlnterface), 
weather); 

} 





Private Sub FetchWeatherFromServer() 

' Simulate the delay from network access. 

Thread.Sleep(4000) 

' Tried and true method for weather forecasting - random numbers. 

Dim rand As New Random() 

Dim weather As String 

If rand.Next(2) = 0 Then 
weather = "rainy" 

Else 

weather = "sunny" 

End If 

' Schedule the update function in the UI thread. 

tomorrowsWeather.Dispatcher.Begininvoke(System.Windows.Threading.DispatcherPriority.Normalj New 
OneArgDelegate(AddressOf UpdateUserInterface), weather) 

End Sub 


To keep things simple, we don't actually have any networking code in this example. Instead, we simulate the 
delay of network access by putting our new thread to sleep for four seconds. In this time, the original UI thread 
still running and responding to events. To show this, we've left an animation running, and the minimize and 
maximize buttons also continue to work. 

When the delay is finished, and we've randomly selected our weather forecast, it's time to report back to the UI 
thread. We do this by scheduling a call to updateuserinterface in the UI thread using that thread's Dispatcher. 
We pass a string describing the weather to this scheduled method call. 

• Updating the UI 

private void UpdateUserInterface(String weather) 

{ 

//Set the weather image 
if (weather == "sunny") 

{ 

weatherindicatorlmage.Source = (ImageSource)this.Resources[ 

"SunnylmageSource"]; 

} 

else if (weather == "rainy") 

{ 

weatherindicatorlmage.Source = (ImageSource)this.Resources[ 

"RaininglmageSource"]; 

} 

//Stop clock animation 
showClockFaceStoryboard.Stop(this)j 
hideClockFaceStoryboard.Begin(this); 

//Update UI text 
fetchButton.IsEnabled = true; 
fetchButton.Content = "Fetch Forecast"; 
weatherText.Text = weather; 


} 





Private Sub UpdateUserInterface(By\/al weather As String) 

'Set the weather image 
If weather = "sunny" Then 

weatherindicatorlmage.Source = CType(Me.Resources("SunnyImageSource"), ImageSource) 
Elself weather = "rainy" Then 

weatherindicatorlmage.Source = CType(Me.Resources("RainingImageSource"), ImageSource) 
End If 

'Stop clock animation 
showClockFaceStoryboard.Stop(Me) 
hideClockFaceStoryboard.Begin(Me) 

'Update UI text 
fetchButton.IsEnabled = True 
fetchButton.Content = "Fetch Forecast" 
weatherText.Text = weather 
End Sub 


When the Dispatcher in the UI thread has time, it executes the scheduled call to updateuserinterface . This 
method stops the clock animation and chooses an image to describe the weather. It displays this image and 
restores the "fetch forecast" button. 

Multiple Windows, Multiple Threads 

Some WPF applications require multiple top-level windows. It is perfectly acceptable for one Thread/Dispatcher 
combination to manage multiple windows, but sometimes several threads do a better job. This is especially true 
if there is any chance that one of the windows will monopolize the thread. 

Windows Explorer works in this fashion. Each new Explorer window belongs to the original process, but it is 
created under the control of an independent thread. 

By using a WPFFrame control, we can display Web pages. We can easily create a simple Internet Explorer 
substitute. We start with an important feature: the ability to open a new explorer window. When the user clicks 
the "new window" button, we launch a copy of our window in a separate thread. This way, long-running or 
blocking operations in one of the windows won't lock all the other windows. 

In reality, the Web browser model has its own complicated threading model. We've chosen it because it should 
be familiar to most readers. 


The following example shows the code. 



<Window x:Class="SDKSamples.Windowl" 

xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
xmlns: x="http://schemas.microsoft.com/winfx/2006/xaml" 
Title="MultiBrowse" 

Height="600" 

Width="800" 

Loaded="OnLoaded" 

> 

<StackPanel Name="Stack" Orientation="\/ertical"> 

<StackPanel Orientation="Horizontal"> 

<Button Content="New Window" 

Click="NewWindowHandler" /> 

<TextBox IMame="newLocation" 

Width="500" /> 

<Button Content="GO!" 

Click="Browse" /> 

</StackPanel> 

<Frame IMame="placeHolder" 

Width="800" 

Height="550"></Frame> 

</StackPanel> 

</Window> 



using System; 

using System.Windows; 

using System.Windows.Controls; 

using System.Windows.Data; 

using System.Windows.Threading; 

using System.Threading; 

namespace SDKSamples 

{ 

public partial class Windowl : Window 

{ 


public WindowlO : base() 

{ 

InitializeComponent(); 

} 

private void OnLoaded(object sender, RoutedEventArgs e) 

{ 

placeHolder.Source = new Uri("http://www.msn.com"); 

} 

private void Browse(object sender, RoutedEventArgs e) 

{ 

placehlolder.Source = new Uri(newLocation.Text); 

} 

private void NewWindowHandler(object sender, RoutedEventArgs e) 

{ 

Thread newWindowThread = new Thread(new ThreadStart(ThreadStartingPoint)) 
newWindowThread.SetApartmentState(ApartmentState.STA); 
newWindowThread.IsBackground = true; 
newWindowThread.Start(); 

} 

private void ThreadStartingPoint() 

{ 

Windowl tempWindow = new Windowl(); 
tempWindow.Show(); 

System.Windows.Threading.Dispatcher.Run 0; 

} 



Imports System.Windows 
Imports System.Windows.Controls 
Imports System.Windows.Data 
Imports System.Windows.Threading 
Imports System.Threading 

Namespace SDKSamples 

Partial Public Class Windowl 
Inherits Window 

Public Sub New() 

MyBase.New() 

InitializeComponent() 

End Sub 

Private Sub OnLoaded(ByVal sender As Object, ByVal e As RoutedEventArgs) 
placeHolder.Source = New Uri("http://www.msn.com") 

End Sub 

Private Sub Browse(ByVal sender As Object, ByVal e As RoutedEventArgs) 
placeHolder.Source = New Uri(newLocation.Text) 

End Sub 

Private Sub NewWindowHandler(ByVal sender As Object, ByVal e As RoutedEventArgs) 

Dim newWindowThread As New Thread(New ThreadStart(AddressOf ThreadStartingPoint)) 
newWindowThread.SetApartmentState(ApartmentState.STA) 
newWindowThread.IsBackground = True 
newWindowThread.Start() 

End Sub 

Private Sub ThreadStartingPoint() 

Dim tempWindow As New Windowl() 
tempWindow.Show() 

System.Windows.Threading.Dispatcher.Run 0 
End Sub 
End Class 
End Namespace 


The following threading segments of this code are the most interesting to us in this context: 

private void NewWindowHandler(object sender, RoutedEventArgs e) 

{ 

Thread newWindowThread = new Thread(new ThreadStart(ThreadStartingPoint)); 
newWindowThread.SetApartmentState(ApartmentState.STA); 
newWindowThread.IsBackground = true; 
newWindowThread.Start(); 

} 


Private Sub NewWindowHandler(ByVal sender As Object, ByVal e As RoutedEventArgs) 

Dim newWindowThread As New Thread(New ThreadStart(AddressOf ThreadStartingPoint)) 
newWindowThread.SetApartmentState(ApartmentState.STA) 
newWindowThread.IsBackground = True 
newWindowThread.Start() 

End Sub 


This method is called when the "new window" button is clicked. It creates a new thread and starts it 
asynchronously. 






private void ThreadStartingPoint() 

{ 

Windowl tempWindow = new Windowl(); 
tempWindow.Show(); 

System.Windows.Threading.Dispatcher.Run(); 

} 


Private Sub ThreadStartingPoint() 

Dim tempWindow As New Windowl() 
tempWindow.Show() 

System.Windows.Threading.Dispatcher.Run() 
End Sub 


This method is the starting point for the new thread. We create a new window under the control of this thread. 
WPF automatically creates a new Dispatcher to manage the new thread. All we have to do to make the window 
functional is to start the Dispatcher. 

Technical Details and Stumbling Points 

Writing Components Using Threading 

The Microsoft .NET Framework Developer's Guide describes a pattern for how a component can expose 
asynchronous behavior to its clients (see Event-based Asynchronous Pattern Overview). For instance, suppose we 
wanted to package the FetchWeathenEnomServer method into a reusable, nongraphical component. Following the 
standard Microsoft .NET Framework pattern, this would look something like the following. 




public class WeathenComponent : Component 

{ 

//gets weather: Synchronous 
public string GetWeather() 

{ 

string weather = 

//predict the weather 
return weather; 

} 

//get weather: Asynchronous 
public void GetWeatherAsync() 

{ 

//get the weather 

} 

public event GetWeatherCompletedEventHandler GetWeatherCompleted; 

} 

public class GetWeatherCompletedEventArgs : AsyncCompletedEventArgs 

{ 

public GetWeatherCompletedEventArgs(Exception error, bool canceled, 
object userState, string weather) 

base(error, canceled, userState) 

{ 

_weather = weather; 

} 

public string Weather 

{ 

get { return _weather; } 

} 

private string _weather; 


public delegate void GetWeatherCompletedEventHandler(object sender, 
GetWeatherCompletedEventArgs e); 



Public Class WeathenComponent 
Inherits Component 
'gets weather: Synchronous 
Public Function GetWeather() As String 
Dim weather As String = "" 

'predict the weather 

Return weather 
End Function 

'get weather: Asynchronous 
Public Sub GetWeatherAsyncO 
'get the weather 
End Sub 

Public Event GetWeatherCompleted As GetWeatherCompletedEventFlandler 
End Class 

Public Class GetWeatherCompletedEventArgs 
Inherits AsyncCompletedEventArgs 

Public Sub IMew(ByVal [error] As Exception, ByVal canceled As Boolean, ByVal userState As Object, ByVal 
weather As String) 

MyBase.New([error], canceled, userState) 

_weather = weather 
End Sub 

Public Readonly Property Weather() As String 
Get 

Return _weather 
End Get 
End Property 

Private _weather As String 
End Class 

Public Delegate Sub GetWeatherCompletedEventFlandler(ByVal sender As Object, ByVal e As 
GetWeatherCompletedEventArgs) 

GetweatherAsync would use OFie of the techniques described earlier, such as creating a background thread, to do 
the work asynchronously, not blocking the calling thread. 

One of the most important parts of this pattern is calling the MethodName completed method on the same 
thread that called the MethodName Async method to begin with. You could do this using WPF fairly easily, by 
storing CurrentDispatcher —but then the nongraphical component could only be used in WPF applications, not in 
Windows Forms or ASP.NET programs. 

The DispatcherSynchronizationContext class addresses this need—think of it as a simplified version of 
Dispatcher that works with other Ul frameworks as well. 


public class Weather'Component2 : Component 

{ 

public string GetWeather() 

{ 

return fetchWeatherFromServer(); 

} 

private DispatcherSynchronizationContext requestingContext = null; 

public void GetWeatherAsync() 

{ 

if (requestingContext != null) 

throw new InvalidOperationException("This component can only handle 1 async request at a time") 
requestingContext = (DispatcherSynchronizationContext)DispatcherSynchronizationContext.Current; 
NoArgDelegate fetcher = new NoArgDelegate(this.fetchWeatherFromServer); 

// Launch thread 

fetcher.BeginInvoke(null, null); 

} 

private void RaiseEvent(GetWeatherCompletedEventArgs e) 

{ 

if (GetWeatherCompleted != null) 

GetWeatherCompleted(thiSj e); 

} 

private string fetchWeatherFromServer() 

{ 

// do stuff 
string weather = 

GetWeatherCompletedEventArgs e = 

new GetWeatherCompletedEventArgs(null, false^ nullj weather); 

SendOrPostCallback callback = new SendOrPostCallback(DoEvent); 
requestingContext.Post(callbackj e); 
requestingContext = null; 

return e.Weather; 

} 

private void DoEvent(object e) 

{ 

//do stuff 

} 

public event GetWeatherCompletedEventFlandler GetWeatherCompleted; 
public delegate string IMoArgDelegate(); 



Public Class Weather'Component2 
Inherits Component 

Public Function GetWeather() As String 
Return fetchWeatherFromServer() 

End Function 

Private requestingContext As DispatcherSynchronizationContext = Nothing 

Public Sub GetWeatherAsyncO 

If requestingContext IsNot Nothing Then 

Throw New InvalidOperationException("This component can only handle 1 async request at a time") 
End If 

requestingContext = CType(DispatcherSynchronizationContext.Currentj 
DispatcherSynchronizationContext) 

Dim fetcher As New NoArgDelegate(AddressOf Me.fetchWeatherFromServer) 

' Launch thread 

fetcher.BeginInvoke(Nothingj Nothing) 

End Sub 

Private Sub [RaiseEvent](ByVal e As GetWeatherCompletedEventArgs) 

RaiseEvent GetWeatherCompleted(Mej e) 

End Sub 

Private Function fetchWeatherFromServer() As String 
' do stuff 

Dim weather As String = "" 

Dim e As New GetWeatherCompletedEventArgs(Nothing, False^ Nothing, weather) 

Dim callback As New SendOrPostCallback(AddressOf DoEvent) 
requestingContext.Post(callback, e) 
requestingContext = Nothing 

Return e.Weather 
End Function 

Private Sub DoEvent(By\/al e As Object) 

'do stuff 
End Sub 

Public Event GetWeatherCompleted As GetWeatherCompletedEventElandler 
Public Delegate Function NoArgDelegate() As String 
End Class 


Nested Pumping 

Sometimes it is not feasible to completely lock up the Ul thread. Let's consider the Show method of the 
MessageBox class. Show doesn't return until the user clicks the OK button. It does, however, create a window that 
must have a message loop in order to be interactive. While we are waiting for the user to click OK, the original 
application window does not respond to user input. It does, however, continue to process paint messages. The 
original window redraws itself when covered and revealed. 




Some thread must be in charge of the message box window. WPF could create a new thread just for the message 
box window, but this thread would be unable to paint the disabled elements in the original window (remember 
the earlier discussion of mutual exclusion). Instead, WPF uses a nested message processing system. The 
Dispatcher class includes a special method called PushFrame, which stores an application's current execution 
point then begins a new message loop. When the nested message loop finishes, execution resumes after the 
original PushFrame call. 

In this case, PushFrame maintains the program context at the call to MessageBox.Show, and it starts a new 
message loop to repaint the background window and handle input to the message box window. When the user 
clicks OK and clears the pop-up window, the nested loop exits and control resumes after the call to Show. 

Stale Routed Events 

The routed event system in WPF notifies entire trees when events are raised. 

<Canvas MouseLeftButtonDown="handler'l" 

Width="100" 

Height="100" 

> 

<Ellipse Width="50" 

Height="50" 

Fill="Blue" 

Canvas.Left="30" 

Canvas.Top="50" 

MouseLeftButtonDown="handler2" 

/> 

</Canvas> 

When the left mouse button is pressed over the ellipse, handier 2 is executed. After handier 2 finishes, the event 
is passed along to the Canvas object, which uses handieri to process it. This happens only if handien 2 does not 
explicitly mark the event object as handled. 

It's possible that handien 2 will take a great deal of time processing this event. handier 2 might use PushFrame to 
begin a nested message loop that doesn't return for hours. If handier 2 does not mark the event as handled 
when this message loop is complete, the event is passed up the tree even though it is very old. 

Reentrancy and Locking 

The locking mechanism of the common language runtime (CLR) doesn't behave exactly as one might imagine; 
one might expect a thread to cease operation completely when requesting a lock. In actuality, the thread 
continues to receive and process high-priority messages. This helps prevent deadlocks and make interfaces 
minimally responsive, but it introduces the possibility for subtle bugs. The vast majority of the time you don't 
need to know anything about this, but under rare circumstances (usually involving Win32 window messages or 
COM STA components) this can be worth knowing. 

Most interfaces are not built with thread safety in mind because developers work under the assumption that a Ul 
is never accessed by more than one thread. In this case, that single thread may make environmental changes at 
unexpected times, causing those ill effects that the DispatcherObJect mutual exclusion mechanism is supposed to 
solve. Consider the following pseudocode: 





























Most of the time that's the right thing, but there are times in WPF where such unexpected reentrancy can really 
cause problems. So, at certain key times, WPF calls DisableProcessing, which changes the lock instruction for that 
thread to use the WPF reentrancy-free lock, instead of the usual CLR lock. 

So why did the CLR team choose this behavior? It had to do with COM STA objects and the finalization thread. 
When an object is garbage collected, its Finalize method is run on the dedicated finalizer thread, not the Ul 
thread. And therein lies the problem, because a COM STA object that was created on the Ul thread can only be 
disposed on the Ul thread. The CLR does the equivalent of a Begininvoke (in this case using Win32's sendMessage 
). But if the Ul thread is busy, the finalizer thread is stalled and the COM STA object can't be disposed, which 
creates a serious memory leak. So the CLR team made the tough call to make locks work the way they do. 

The task for WPF is to avoid unexpected reentrancy without reintroducing the memory leak, which is why we 
don't block reentrancy everywhere. 


See also 

• Single-Threaded Application with Long-Running Calculation Sample 











WPF Unmanaged API Reference 
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Windows Presentation Foundation (WPF) libraries expose a number of unmanaged functions that are intended for 
internal use only. They should not be called from user code. 

In This Section 

Activate Function 

CreatelDispatchSTAForwarder Function 
Deactivate Function 
ForwardTranslateAccelerator Function 
LoadFromHistory Function 
ProcessUnhandledException Function 
SaveToHistory Function 
SetFakeActiveWindow Function 

See also 

• Advanced 




Activate Function (WPF Unmanaged API Reference) 

1/24/2020 • 2 minutes to read • Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management. 

Syntax 

void Activate( 

const ActlvateParameters* pPanametenSj 

_deref_out_ecount(l) LPUNKNOWN* ppInneCj 

); 


Parameters 

pPanametens 

A pointer to the window's activation parameters. 

ppinner 

A pointer to the address of a single-element buffer that contains a pointer to an lOleDocument object. 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll 
In the .NET Framework 4 and later: PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 







CreatelDispatchSTAForwarder Function (WPF 
Unmanaged API Reference) 

3/12/2020 • 2 minutes to read i Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for thread and windows management. 

Syntax 

HRESULT CreateIDispatchSTAForwar'der( 

_in IDispatch *pDispatchDelegatej 

_denef_out IDispatch **ppFonwarden 

) 


Parameters 

Property Value/Return Value 

pDispatch Delegate 
A pointer to an IDispatch interface. 

ppForwarder 

A pointer to the address of an IDispatch interface. 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5; PresentationHostDLL.dll 
In the .NET Framework 4 and later; PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 







Deactivate Function (WPF Unmanaged API 
Reference) 

1/24/2020 • 2 minutes to read • Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management 

Syntax 

void DeactivateO 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll 
In the .NET Framework 4 and later: PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 





ForwardTranslateAccelerator Function (WPF 
Unmanaged API Reference) 

3/12/2020 • 2 minutes to read i Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management. 

Syntax 

HRESULT ForwardTranslateAccelerator( 

MSG* pMsgj 

VARIANT_B00L appUnhandled 

) 


Parameters 

pMsg 

A pointer to a message. 
appUnhandled 

true when the app has already been given a chance to handle the input message, but has not handled it; 
otherwise, false . 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll 
In the .NET Framework 4 and later: PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 







LoadFromHistory Function (WPF Unmanaged API 
Reference) 

3/12/2020 • 2 minutes to read i Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management. 

Syntax 

HRESULT LoadFromHistory_export( 

IStream* pHistoryStreamj 
IBindCtx* pBindCtx 


Parameters 

pHistoryStream 

A pointer to a stream of history information. 
pBindCtx 

A pointer to a bind context. 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5; PresentationHostDLL.dll 
In the .NET Framework 4 and later; PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 





ProcessUnhandledException Function (WPF 
Unmanaged API Reference) 

1/24/2020 • 2 minutes to read • Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for exception handling. 

Syntax 

void _stdcall ProcessUnhandledException( 

_in_ecount(l) BSTR erronMsg 

) 


Parameters 

errorMsg 

The error message. 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll 
In the .NET Framework 4 and later: PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 





SaveToHistory Function (WPF Unmanaged API 
Reference) 

1/24/2020 • 2 minutes to read • Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management 

Syntax 

HRESULT SaveToHistor'y( 

_in_ecount(l) IStream* pHistoryStream 

) 


Parameters 

pHistoryStream 

A pointer to the history stream. 

Requirements 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; 

In the .NET Framework 3.0 and 3.5: PresentationHostDLL.dll 
In the .NET Framework 4 and later: PresentationHost_v0400.dll 
.NET Framework Version; Available since 3.0 

See also 


• WPF Unmanaged API Reference 





SetFakeActiveWindow Function (WPF Unmanaged 
API Reference) 

1/24/2020 • 2 minutes to read • Edit Online 


This API supports the Windows Presentation Foundation (WPF) infrastructure and is not intended to be used 
directly from your code. 

Used by the Windows Presentation Foundation (WPF) infrastructure for windows management. 

Syntax 

void _stdcall SetFakeActiveWindow( 

HWND hwnd 

) 


Parameters 

hwnd 

A window handle. 

Requirements 

Platforms; See .NET Framework System Requirements. 

DLL; PresentationHost_v0400.dll 

.NET Framework Version; Available since 4 

See also 


• WPF Unmanaged API Reference 





